Documentation fails in a specific and predictable way: it describes the software instead of the task. A page titled "The Export dialog" listing every control is easy to write, complete, and useless to someone trying to get a report to their accountant. Good documentation starts from what the reader is trying to do, and that single shift accounts for most of the difference between docs people use and docs people complain about.
Four kinds of document, doing four jobs
The most useful framework here — often credited as the Diátaxis approach — separates documentation into four types that should not be mixed:
Tutorials teach a beginner by having them do something successfully. The goal is confidence, not coverage. A tutorial has a single path, no options, and a working result at the end. It is written for someone who does not yet know enough to make choices, so you make the choices for them.
How-to guides solve a specific problem for someone who already knows the basics. "How to export a filtered report to CSV." Task-titled, step-by-based, assumes competence, and does not explain the underlying concepts.
Reference describes the machinery exhaustively and accurately: every parameter, every field, every error code. Optimised for lookup, not reading. Consistency and completeness matter more than prose.
Explanation provides understanding: why the system works this way, what the trade-offs were, how the concepts relate. Read away from the keyboard.
Most bad documentation is one document trying to be all four. A tutorial interrupted by a table of every configuration option loses the beginner; a reference page padded with narrative loses the expert. Separating them makes each one better and each one easier to write.
Start from tasks, not features
Write the table of contents as a list of things the reader wants to do, phrased in their words:
- "Send an invoice to a client" — not "The Invoice module"
- "Recover a document you deleted" — not "Trash and retention settings"
- "Give someone access without letting them edit" — not "Permission levels"
Two benefits. Readers find things, because they search for their task and not for your feature name. And writing task-first exposes gaps: a feature nobody can construct a task around may be a feature nobody needs, which is useful information.
Where do the tasks come from? Support tickets, search logs on your own docs site, and the questions people ask in onboarding. All three are real data and all three are usually available and unused.
Writing steps that work
For how-to content, the mechanics matter:
- Number sequential steps. Bullets for lists of alternatives, numbers for sequences.
- One action per step. "Click Settings, then Advanced, then scroll to Export and set Format to CSV" is four steps pretending to be one, and the reader loses their place.
- Say where before what. "In the sidebar, click Settings" lets the reader's eye go to the right place before it looks for the control.
- Use the exact label from the interface, in bold, including its capitalisation. If the button says "Save changes", do not write "click Save".
- State the result of steps that produce a visible change. It is how the reader knows they are on track, and how they detect that they are not.
- Put prerequisites at the top, not in step six. Discovering at step six that you needed administrator access is the most annoying experience in documentation.
- Say what success looks like at the end.
Screenshots: useful and expensive
Screenshots help enormously for orientation — "here is what this screen looks like" — and much less for individual steps, where good text is usually clearer. They are also the highest-maintenance content you can write: every interface change invalidates them, and stale screenshots actively mislead, sending readers looking for a button that no longer exists.
A reasonable policy:
- One orientation screenshot per major screen, not one per step.
- Annotate with callouts rather than relying on the reader spotting the right control.
- Crop tightly to the relevant region so it survives minor layout changes.
- Never put essential information only in an image — it is invisible to search, to translation, and to screen readers. If a screenshot carries text the reader needs, repeat it in prose. See how to add alt text to PDF images for the accessibility mechanics when the docs are distributed as PDFs.
- Keep the source files for annotated images, so a small change does not mean redrawing.
Language
- Second person, present tense, active voice. "Click Save" — not "the user should click Save" or "Save should be clicked".
- Consistent terminology. One name per thing, everywhere. If it is a "workspace" in the interface, it is never a "project" in the docs. Keep a term list, alongside the rest of the shared reference material — see building a team knowledge base.
- Short sentences. Documentation is read under mild stress by people who want to be doing something else.
- No jokes that depend on cultural knowledge, and few jokes generally — they age badly and translate worse.
- Write for translation if you will ever translate: short sentences, no idiom, no puns, consistent phrasing for repeated instructions.
Broader craft: plain language business documents and workplace writing for non-native English speakers.
Maintenance is the real problem
Writing documentation is a project; keeping it true is an ongoing cost, and it is the one organisations fail to budget for. Stale documentation is worse than none, because it is trusted.
What works:
- Docs change in the same pull request as the code. Anything else drifts. This is the single most effective practice available.
- An owner per section, a role rather than a person.
- A review date on each page, visible to readers. "Last reviewed March 2026" lets a reader calibrate their trust.
- Feedback on every page — a "was this helpful" control, or a link to raise an issue. The complaints tell you where to work.
- Delete aggressively. Documentation for removed features, superseded procedures, and abandoned integrations should go. A large documentation set that is mostly obsolete is harder to use than a small current one.
- Watch the search logs. Queries that return nothing are a to-do list written by your users.
The version discipline is the same as any other governed document: document versioning best practices and employee handbooks and policy documents for the internal-policy equivalent.
Format and delivery
Web-first for anything that changes: searchable, linkable, always current, and accessible on any device.
PDF where the documentation must be fixed, printed, shipped with a product, or retained as a record of what the system did at a point in time — regulated environments, validated systems, and offline field use. If you produce PDFs, generate them from the same source rather than maintaining them separately, and make sure they are properly tagged: reading order in tagged PDFs and PDF accessibility guide.
The comparison in general: PDF vs HTML.
Docs-as-code — Markdown in the repository, reviewed like code, built into a site — is the practice that makes "update the docs in the same change" realistic. It is also what makes multiple output formats cheap.
Testing documentation
The only reliable test is watching someone use it.
Give a new user a task and the documentation, and watch without helping. Every hesitation is a defect. The parts you were confident about will fail, and the parts you agonised over will pass unremarked. Half an hour of this is worth more than any amount of internal review, and it is the step that gets skipped.
Failing that, the cheapest proxy: follow your own instructions on a clean account, doing exactly and only what they say. Documentation written by someone who knows the system is full of unstated steps that are invisible until you are forced to perform them literally.
Summary
Separate tutorials, how-to guides, reference and explanation rather than blending them, and title everything by the reader's task rather than your feature. Write steps that do one thing each, name controls exactly as the interface does, and put prerequisites at the top. Use screenshots for orientation and text for instruction, since screenshots are the first thing to go stale. Then treat maintenance as the main cost: docs updated in the same change as the code, a review date on every page, and someone watching a real user try to follow them.
