Large documentation sets go stale, and stale documentation is worse than none because people trust it. We keep three documents and defend the boundary.
1. The README, for the next engineer
Get the project running, run the tests, deploy a change, roll it back. Verified whenever someone new joins, because that is the only reliable test of whether it works.
2. The conventions file, for everyone writing code
How this codebase handles errors, names things, accesses data and structures tests. Short, opinionated, and now doubling as context for model-assisted work — which has had the pleasant side effect of keeping it current.
3. The decisions log, for the future
One short entry per significant decision: what we chose, what we rejected, why, and what would make us revisit. Appended to, never rewritten.
Documentation that describes what the code does is redundant. Documentation that describes why it does it cannot be recovered any other way.
What we deliberately do not write
Generated API descriptions nobody reads, architecture diagrams that drift within a month, and process documents describing how work should feel. If a document has no named reader, it does not get written.