We have handed over enough codebases to know which documents get opened and which ones get skimmed once and never touched again. The list is shorter than most process guides suggest.
Three documents that earn their place
- How to run it. One page, from a clean machine to a working local site, with the actual commands. If it takes longer than fifteen minutes, the document is wrong, not the reader.
- Why it is shaped like this. The four or five decisions that would otherwise look arbitrary, each with the alternative that was rejected and the reason.
- What will bite you. The known sharp edges, written plainly. Every codebase has them and pretending otherwise just moves the discovery to a Friday evening.
What we stopped writing
Architecture diagrams that go stale in a sprint. Function-by-function API references that the code already states more accurately. A glossary nobody asked for.
Documentation competes with reading the source. Write only what the source cannot say.