step 27 / 32 · 5 min
Writing for the person who comes next
Documentation gets written badly because people write it for the wrong reader, or write the part the code already covers.
What the code cannot say
Code says what it does. It cannot say:
- why this approach, and what was rejected
- what this looks wrong but correct thing is handling
- what breaks if you change it
- what we deliberately did not do, and under what condition to revisit
That is the expensive knowledge, and it is the part that leaves with people.
The kinds, and their readers
| Kind | Reader | Wants |
|---|---|---|
| README | a new joiner | run it in ten minutes |
| Architecture notes | an engineer changing it | why it is shaped like this |
| API reference | someone integrating | exact request and response |
| Runbook | on call at 3am | steps, in order, no prose |
| Decision record | six months from now | the reasoning and alternatives |
Mixing them produces a document that serves nobody. A README containing architecture rationale buries the setup instructions the reader actually came for.
A README that works
# Orders Service
One paragraph: what it does and who calls it.
## Running locally
Exact commands, copy-pasteable, tested on a clean machine.
## Architecture
A paragraph and a diagram. Link out for detail.
## Common tasks
Run the tests. Add a migration. Deploy.
## Gotchas
The things that waste a day if you do not know them.The last section is the one people skip and the one most read.
Decision records
A short file per significant decision:
# 2026-03: Postgres rather than DynamoDB
## Context
Reads outnumber writes 50:1. We need ad hoc reporting queries.
## Decision
Postgres with read replicas.
## Consequences
Ad hoc queries are easy. Horizontal write scaling will need work
if writes grow 10x; revisit at 2,000 writes per second.
## Alternatives
DynamoDB: scales writes better, no ad hoc queries without a second store.Five minutes to write, and it answers "why on earth did they choose this" for years, including for the person who chose it.
Keeping it true
Documentation drifts, and stale documentation is worse than none because it is believed.
The defences: put it next to the code so it is in the same review, generate what can be generated from the code, and prefer executable documentation, since a test cannot drift and a runbook command can be scripted.
And write less. A short accurate document is maintained. A forty page one is abandoned in month two.