A platform team's documentation is comprehensive and its users still ask questions it answers. What is wrong with the writing?
Show the full answer Hide the answer
What is usually wrong
It is organised by the system's structure rather than by the reader's task. A reference organised around components requires the reader to already know which component solves their problem, which is precisely what they do not know.
The second failure: no distinction between the four kinds of documentation, which have different purposes and cannot be mixed.
- Tutorial: learning-oriented, for someone with no context, taking them through a working example.
- How-to: task-oriented, for someone who knows what they want and needs the steps.
- Reference: information-oriented, complete and precise, consulted rather than read.
- Explanation: understanding-oriented, the why and the trade-offs.
Mixing them produces a document that serves none of the four readers. A tutorial interrupted by reference detail loses the beginner; a reference with narrative explanation is unusable for lookup.
What makes technical documentation work
- Start from the question the reader has, and make the page title that question. Search brings people to a page, so the page must match a question rather than a component name.
- A complete, runnable example in every how-to. Readers copy the example, which means an example with a placeholder they must fill in from elsewhere fails.
- Document the failure modes and the error messages. Searching for an error message is the single most common documentation query and is usually unanswered.
- State the version. Documentation that does not say what it applies to is unusable in a fast-moving product.
- Explain the model once, properly. Users who understand the underlying model answer their own questions; users who only have recipes ask about every variation.
The signal to use
The questions users actually ask are the documentation backlog, ranked by frequency. A support channel is a better roadmap for documentation than any internal review, and treating it that way closes the loop that makes documentation improve rather than merely grow.