One page, one job
Most unhelpful documentation is unhelpful because one page tries to do several jobs. There are four:
- Tutorial: teaches by doing. A beginner follows it from start to finish and ends up with something that works. It makes the decisions for the reader.
- How-to: solves one problem for someone who roughly knows what they are doing. It assumes context and gets to the point.
- Reference: describes what exists. Complete and accurate, looked up rather than read.
- Concept: explains why things are the way they are. Read away from the keyboard.
A tutorial that stops to explain the architecture loses the beginner. A reference page that assumes you followed the tutorial is no use to someone arriving from search. Decide which kind a page is and keep 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 must stand on its own: say what it is about in the first sentence, and link to what came before instead of assuming it was read.
Say what is easy to get wrong
The most valuable sentence in most documentation warns about the mistake everyone makes. If you have watched three people trip over the same thing, put it on the page in plain words, not in a footnote.
Keep it current
Documentation that is slightly out of date is worse than none, because people trust it. When something changes, updating the docs is part of the change, not a task for later.
Shape
Use headings a reader can scan, and short paragraphs. Use a list when the content is a list, and sentences when it is an argument: a page of bullets with nothing connecting them is harder to follow than it looks.