Do Support Docs Belong in the QA Toolkit?

Hey you wonderful MoTers :waving_hand:

As QAs / SDETs in agile teams, do you create or influence support documentation (internal or customer‑facing) as part of your quality‑infusing role?

I’m curious how others approach this:

  • What are your non‑negotiables for good support docs?

  • What have you learned to avoid because it adds noise or goes stale?

  • How deep do you usually go—just enough to unblock, or proper technical deep dives?

  • How do you decide what must be documented vs what should stay in code/tests?

  • Who actually owns the docs, and how do you stop them rotting?

  • Do bugs, incidents, or support tickets ever drive doc updates?

Bonus curiosity:

  • Have you seen support documentation meaningfully improve quality, reduce defects, or help teams move faster?

  • Or is it still treated as “nice to have” in most agile setups?

Would love to hear real experiences, strong opinions, and lessons learned—especially the uncomfortable ones :grinning_face_with_smiling_eyes:.

PS: A :star: will be rewarded for answers :wink:

I think they do, I try to fix and even write bits of support and external documentation from time to time in my role.

Huge docs go stale, I’m working on a doc that needs splitting up in order to make updating it even remotely possible… How do you eat an elephant? One bit at a time.

As far as code and test docs, having up to date docs on how to find and how to install , prepare and start the tests is enough. The tests themselves should not need documentation, if they are that cryptic to understand, then they are perhaps, not really tests.

1 Like

As a QA we do influence documentation … If a feature is bug free but is so confusing that support is flooded with support tickets then its a quality failure…. A good documentation should have this 5 min rule a user external/internal whoever reads the doc should be able to resolve the error within 5mins … Also Documentation should avoid any screenshots , those are things that goes stale in first place…Also who is intended user of this documentation? customer facing documents should focus on resolving and unblocking outcome user wants , not exactly how the database handles the transaction.

3 Likes

I’ve never called myself a QA or SDET, but I have influenced support documentation a great deal, depending on how you look at it.

Internally I’ve written a lot of work to help others. As I investigate archaic parts of the software and unpick it I will often write them up to save others the same pain. I think that many test artifacts, such as testing notes and bug reports, act as support documents internally. I’ve helped to find problems with oracles like supporting documentation, or problems with the software depending on where the misalignment falls.

Customer-facing documents I tend to have less influence over in a direct sense, but I consider them part of the product and therefore always worth considering for testing, even (or especially) if told otherwise.

What are your non‑negotiables for good support docs?

That I’m permitted to do work on them that I consider to be good. It depends heavily on the situation and how important the documents are, if there are other teams in charge of them, and so on.

What have you learned to avoid because it adds noise or goes stale?

Everything, in a sense. Investigation is a cost, and documentation of any kind is between one and two costs depending on if it has to be maintained. Every decision is based on what makes sense. If the system will change, if the documentation is mandated, how detailed it needs to be, if it covers something critical, who the audience is, who has access to it, and so on.

How deep do you usually go—just enough to unblock, or proper technical deep dives?

Depends on if it needs one. I won’t go off on a technical crusade without good reason, as it’s part of my job not to deliberately waste time and resources. Usually, I suppose, I do the minimum. Sometimes the minimum is a lot.

How do you decide what must be documented vs what should stay in code/tests?

I suppose that depends on what “must be documented” means. In the cosmic sense, nothing need ever be documented. So it depends on what pressures are on me to write things down. Some are self-imposed, such as writing testing notes for my own use, but perhaps I need to run a debrief and therefore need notes I can read the next day and remember what I did in more detail.

Who actually owns the docs, and how do you stop them rotting?

The owner can vary. As a tester I don’t stop rot, I discover and report it. As I say I think documentation is a big cost. Only write down what’s valuable enough for the situation.

Do bugs, incidents, or support tickets ever drive doc updates?

Depending on what we consider support documentation, yes. Sometimes bugs can drive documentation creation - I’ve written internal documents based on testing I’ve done following a bug.

Have you seen support documentation meaningfully improve quality, reduce defects, or help teams move faster?

Yes, I’ve been thanked for writing internal documents before where it’s saved others a great deal of time. Test artifacts obviously can be used for reporting.

Or is it still treated as “nice to have” in most agile setups?

I don’t think documentation should be an expensive luxury we pour money into because it makes the place look nice. It will depends on what is needed. Often in agile businesses I find that documentation is born from pain, like teenage poetry, and expires when the trust in it expires. Writing it “just in case” is something you only do at the start of your career when you realise how it goes unread (because one does not consider the audience and use cases) and how costly it is (when you realise that projects outpace documents and updating documents is a finite resource)

Just to try to be useful here’s some considerations for documenting part of some software:

  1. Is it important? If this part of the software is important it may benefit from documentation despite the maintenance costs.
  2. Will it change? If this part of the software won’t change then documentation may stay relevant for longer, reducing the maintenance costs.
  3. Who might need support? If you can think of a reasonably likely situation where someone might need this supporting document that helps defend the cost of it. That person will also need to know the document even exists.

And also support documents, especially those for users, are testable artifacts and can benefit from early involvement with testers. I don’t think it’s a testers job to create typical support documentation, but sometimes it’s created as part of testing and there’s no reason not to make that available to people.

3 Likes

I tend to test documentation as a product deliverable and give feedback.

I am not a documenter though, my own style of writing is naturally overkill for general public and my grammar sucks.

I’d be looking to move most documentation to AI with the usual human in the loop aspect, its likely already better than I am at this sort of thing given I am not a pro documentor.

3 Likes

Could you explain what you mean by “support docs”? In my head, all our documentation could fall under this category, because if it’s not supporting someone somehow, it’s probably useless and shouldn’t exist :upside_down_face: But yes, I’ve always both created and influenced documentation. In my experience, it’s (best as) a shared responsibility within the team - everyone should feel empowered to create / improve documentation, and no one should feel like the burden falls solely on them.

The depth and style / format of the documentation also depends greatly on the target audience and intended purpose / use. In general, I think it should be enough to move people forward, but not so much that it stops being useful / used, or almost blocks or discourages discussion.

If things are living documents, likely to evolve in future, only represent one perspective, etc., I like to make that explicit, as I often find that people think what is documented is “official” and often not open to discussion, the latter of which is almost never the case for me.

2 Likes

If we have documentation that helps accelerate the delivery of quality, then it’s an essential artifact across the SDLC, and the quality traits we care about for that artefact should be monitored and preserved by the team.

But historically that’s been hard to enforce, as other commenters have also noted. Personally I’ve seen good examples, and bad examples. With AI-integrated workflows becoming more common, however, there’s an opportunity to treat it like code. As organisations integrate AI agents into workflows, docs become input for RAG pipelines, coding agents, support automation.

This means you can run automated evaluations against doc quality in ways we couldn’t before. It also opens up failure modes, though, like context drift. And the harder question is whether the assembled context is actually right for a given goal, or a lot of it is noise.

To make it concrete. With a previous team I’d written a document laying down our agreed guidelines for test automation practice. Were those guidelines followed by developers? Kind of. Maybe. Hard to evaluate. If that document becomes context for an agent generating code and tests, you know it’s being used. The inclusion has a more direct effect on quality of process and product. And there’s more drive to evaluate that effect, because we’re intentionally using the doc. If you steer it well, I think the effect can be positive.

2 Likes

In today’s AI‑driven environment, many teams rely on AI tools to create and update documentation. This can give the impression that documentation isn’t a priority for them.

This can give the impression that documentation isn’t a priority for them.

If I understand you correctly, you’re saying that because AI makes it easy to generate docs, teams treat them as sort of a solved problem. That’s a real risk. If AI generates the docs and AI also consumes them, the quality question can become harder to see. The bottleneck then shifts to evaluating those documents, which is not trivial.

1 Like

Totally agree. Docs created by AI are extensive and bloated. Teams do not check them, barely read them, and as they look “right”, add them into the project. Result: No one read/maintain them ever after.

The thing is, as a user not a tester I will pretty much never read documentation. If I have a question I’ll AI to extract the information I need from the documentation in order to do whatever task in hand I have.

Making documents AI friendly is becoming almost more important than the human centric aspect.

Using AI tools here makes sense, I do not see this aspect at all. “This can give the impression that documentation isn’t a priority for them.”, the opposite could be also easily argued and when you have two opposing arguments it tends to also make sense to find a balance.

1 Like

Yes, this same topic about docs came up elsewhere this week (at work) and made me realise, that AI generated docs are effectively pointless. They are a bit like generating a binary in your build system, and then never testing that binary and never shipping it to customers either. A crutch. Just, don’t generate stuff nobody cared about in the first place.

Building metadata for consumption by an AI, is a different matter, an optimisation really, and needs to not be called documentation. Testers need to always be very careful when we allow people to use names , that do not mean what we all mean.

Fortunately, documents are still created by humans where I work. I’m trying to make them more valuable by using AI to compare new stories/requirements against existing documentation to flag risks and gaps etc early on. The process still leaves us in control in terms of decision making i.e. were any of the issues flagged in the tool relevant. Longer term, I am hoping it will ensure documentation is kept up to date and doesn’t become stale.