Documentation is read under pressure
Nobody browses internal docs for pleasure. They are opened when something is broken, when someone is new, or when a decision is being questioned — three moments with very different needs and no patience.
1. How to run it
Exact commands to get the thing working locally, verified by someone who didn’t write them. This is the single most-read document in any repository and the most frequently out of date — and it belongs in what a handover includes.
2. How to deploy and undo
The release process and the rollback path, written for someone doing it at 2am under pressure. If it exists only in someone’s head, that person is a single point of failure — which is what production-ready means.
Write for the person who is tired, alone, and needs this working in ten minutes.
3. Why the significant decisions were made
A short record per major choice: what was picked, what was rejected, and why. It prevents relitigating settled questions and lets a future team tell when the reasoning has genuinely expired.
4. Where things are and what they connect to
A map of services, dependencies, and integrations. This is how you avoid discovering an integration nobody owns during an incident.
Keep it next to the code
Docs in the repository get updated in the same change as the thing they describe; docs in a separate wiki drift immediately. Proximity does more for accuracy than any process for reviewing documentation.
And delete what has gone stale. Wrong documentation is worse than none, because it is trusted for exactly as long as it takes to cause a problem.