The worst documentation I have ever read was not wrong. It described every option, every parameter, every error code, and it was maintained by people who clearly cared. It was still useless, because it never told me what to do.
Accuracy is the easy half. The hard half is answering the question the reader arrived with.
Four kinds of page, never mixed
Nearly every documentation problem I have seen comes from one page trying to be two things. There are four kinds, and mixing them is what produces the ten thousand word page that helps nobody:
- A tutorial takes a beginner from nothing to one working result. It makes the decisions for them.
- A how-to answers one specific question for somebody who already has a working setup.
- A reference lists what exists, exhaustively and dryly.
- An explanation covers why the thing is shaped the way it is.
The tutorial should not list alternatives. The reference should not teach. When a reader is stuck and finds a page that keeps pausing to discuss trade-offs, they do not feel informed, they feel abandoned.
Start every page with who it is for
One line at the top: who this is for, and what they will have at the end. "This assumes you already have an account and want to add a second sender address. At the end you will have one verified."
That single sentence saves more reader time than any amount of restructuring further down, because most wasted reading happens before somebody realises they are on the wrong page.
Write the failures in
The section people actually need is the one that says what happens when it does not work. Not a generic troubleshooting page at the end, but the failure sitting next to the step that produces it.
If a command takes thirty seconds the first time, say so, or every reader will assume it has hung. If a value has to propagate before the next step works, say how long. Documentation that only describes success is a description of a demo.
Show the whole thing once
Every tutorial should end with the complete working result in one block, with nothing left out. Fragments assembled across nine sections are how readers introduce mistakes that neither of you can find afterwards.
Somebody reading documentation is not curious. They are blocked. Write for a person with a problem and a clock.
Maintenance is a structural problem
Documentation rots wherever it duplicates. If the same version number appears on six pages, five of them will be wrong within a year. Keep every fact in exactly one place and link to it, keep examples in a form you can actually run, and delete pages that describe things nobody uses instead of updating them out of politeness.
The measure of good documentation is not length or coverage. It is how often somebody has to ask a human afterwards.
Written by
Ari Bennett
Software engineer and writer
I build web software for a living and write about the parts that are hard to search for: the trade-offs, the dead ends, and the small habits that make a codebase pleasant to come back to a year later. A decade in, I still keep a paper notebook next to the keyboard.
More about the writer
