Most documentation is not read
Long documents describing what the code does go stale within months and are consulted by nobody, because the code itself is a more reliable description.
Document what the code cannot say: how to run it, what to do when it breaks, and why a decision was made.
Three documents worth having
- A setup guide — how to get it running locally, tested by someone who has not done it
- A runbook — what breaks, how to tell, what to do about it
- A decisions record — why particular choices were made
The setup guide is the practical test
If a competent developer cannot get the service running from the documentation within a day, the documentation is incomplete regardless of its length.
- Every prerequisite named with a version
- Every configuration value listed with an example
- The steps in order, tested by following them
- What success looks like at the end
The runbook is what you need at 7am
| Entry | Contains |
|---|---|
| Each alert | What it means, first three checks |
| Deployment | Steps, and how to roll back |
| Scheduled jobs | What runs when, and what if it did not |
| Dependencies | Who to contact at each provider |
| Common problems | Symptom and resolution |
Record decisions as you make them
Why a particular approach was chosen, what was rejected and why, and which apparent oddities are deliberate. Written at the time, in a paragraph.
That record stops the next developer from re-litigating a settled decision or removing something that turns out to be load-bearing.