Documentation Practice
Writing what will be read, keeping it true, and deliberately not writing the rest.
Definition
The discipline of producing documentation that survives. The default failure is not too little documentation but too much of the wrong kind, which is stale, distrusted, and therefore worse than nothing.
The test for whether to write something
Who reads this, when, and what decision or action does it support?
If the answer is vague, do not write it. Documentation without an identified reader is written for the author's sense of completeness and is maintained by nobody.
What is worth writing
- Decisions and their rationale, including rejected options and revisit conditions.
- A context diagram — what the system talks to and what happens when each dependency fails.
- Invariants — what must remain true and is not obvious from the code. This is what the next person will otherwise break in their second week.
- Operational reality — what pages, what it means, which alert is known-noisy and why.
- Known problems — the shortcut, the thing that breaks at 3x traffic, the deprecated dependency. The most generous thing to leave behind, and the most often omitted because it is unflattering.
What is not worth writing
- Anything the code says more accurately — endpoint lists, configuration keys, class structures.
- Anything stale within a month — instance counts, current traffic, the state of a migration.
- Complete inventories, which are wrong within a quarter and teach nothing.
Keeping it true
- Date and owner on everything. An undated document cannot be trusted and will not be.
- Store it with the code, so it is found and updated by people working on the system.
- Derive rather than document where possible — generate the dependency map from observed traffic, the inventory from deployment metadata. Derived artefacts cannot go stale.
- Delete aggressively. A wrong document is worse than a missing one, because people act on it.
- Tie updates to events that already happen — a deployment, a decision, a decommissioning — rather than to a periodic refresh nobody funds.
The framing that produces the right output
Write for the person woken at 3am in four months. They need to know what the system talks to, what breaks, what must stay true, and why it is like this. They do not need a catalogue.
Interview question
"You have two hours to document a system before handing it over. What do you write and what do you deliberately leave out?"