On writing documentation nobody reads
Our internal documentation was comprehensive and useless. Eight pages on a service, and a new engineer still asked the same three questions in their first week. The documents were written for the wrong moment.
Four kinds, four moments
- Tutorial: someone has twenty minutes and a goal. Teach by doing.
- How-to: someone has a problem and knows the shape. Give the steps.
- Reference: someone needs a fact. Be complete and boring.
- Explanation: someone wants to understand a decision. Be brief.
The failure mode is a document that tries to be all four at once, which is what our eight-pager was. Splitting it into a README with a five-step quickstart, a reference comment block, and one decision record took an afternoon.
The test that keeps it honest
Every document gets one reader who is told to follow it literally and report where they get stuck. Any step that requires knowledge the document does not contain is a bug. We fixed eleven of those in the first pass, six of them in the tutorial, which is exactly the document nobody had audited.