Documentation Worth Writing (and What to Skip)
Key takeaway
Write the documents that answer questions the code can't: why a decision was made, how to operate the system at 3am, and how a new engineer gets running on day one. Skip anything that duplicates the code, because it will drift out of date and mislead someone.
Every team agrees documentation matters and most produce very little, because the documents usually proposed are the ones nobody reads. The way out is to be selective: write what has a reader and a moment of need.
Worth writing
- Architecture decision records — one page per significant decision: the context, the options, the choice, and the consequences. These answer "why on earth is it like this?" years later, and that question costs more time than any other.
- Runbooks — what to do when a specific alert fires, written so someone half-awake can follow it. The best time to write one is immediately after an incident.
- Onboarding guide — how to get the system running locally, in order, verified by having the next new joiner follow it exactly.
- The domain glossary — what your business terms actually mean, which prevents a remarkable number of bugs.
- API documentation for anything consumed by another team or customer, generated from the specification so it can't drift.
Usually not worth writing
- Prose descriptions of how the code works. The code is the accurate version; the document becomes a lie within a month.
- Exhaustive comments restating what a line does. Comment why, not what.
- Large design documents written before the work and never revisited.
- Step-by-step guides with screenshots of an interface that changes weekly.
- Anything nobody has ever asked for. Write documentation in response to a real question.
Keep it close to the code
Documentation in the repository, reviewed in the same pull request as the change it describes, stays current. Documentation in a separate wiki drifts, because updating it is a separate act of virtue. Where a document must live elsewhere, link to it from the code and give it an owner and a review date.
Test it the only way that works
Hand the onboarding guide to the next new engineer and watch without helping. Every point where they get stuck is a gap, and the exercise takes an afternoon. Do the same with a runbook during a drill rather than during an incident.