One page, one job
Most unhelpful documentation is unhelpful because a single page is trying to do several jobs at once. It is worth naming the four kinds:
- Tutorial — teaches by doing. A beginner follows it start to finish and ends up with something working. It makes decisions for the reader.
- How-to — solves one specific problem for someone who already knows roughly what they are doing. Assumes context, gets to the point.
- Reference — describes what exists. Complete, accurate, consulted rather than read.
- Concept — explains why things are the way they are. Read away from the keyboard.
A tutorial that stops to explain architecture loses the beginner. A reference page that assumes you followed the tutorial is useless to someone arriving from search. Decide which one a page is, put that in its content type, and stick to it.
Write for someone arriving from search
Most readers do not start at page one. They land in the middle from a search result. So each page needs to stand on its own: say what it is about in the first sentence, and link to what came before rather than assuming it.
Say the thing that is easy to get wrong
The highest-value sentence in most documentation is the one warning about the mistake everyone makes. If you have watched three people trip over the same behaviour, that belongs on the page in plain language — not in a footnote.
Keep it current
Documentation that is subtly out of date is worse than none, because it is trusted. When something changes, fixing the docs is part of the change, not a follow-up task.
Practical shape
Use headings a reader can scan. Prefer short paragraphs. Use a list when the content is genuinely a list, and prose when it is not — a page of bullets with no connecting argument is harder to follow than it looks.