A developer-tools company has a fifty-page architecture document that nobody reads and a set of diagrams that are eight months stale. What should be written instead?

Why it went stale

Documentation decays at a rate proportional to how far it sits from the thing it describes and how much it restates what the code already says. A fifty-page document describing current structure is doomed: the structure changes weekly and the document changes when someone is shamed into it.

What survives

• Decision records. An ADR describes a decision at a moment, with its context and the options rejected. It is never stale, because it was always historical — that property alone makes it the highest-value artefact per word.
• A context diagram. One page: the system, its users, and the external systems it depends on. It changes a few times a year and it is what every new joiner and every security reviewer actually needs.
• A container diagram, if and only if someone maintains it. Level 3 and below should be generated from code or not exist.
• The things that are not derivable: why the sync path has its own datastore, why this queue is deliberately not Kafka, which failure the odd-looking retry policy exists to prevent. Rationale is the only content code cannot carry.

The test to apply

For every page ask: who reads this, when, and what decision does it change? Pages that cannot answer get deleted. This usually removes most of the volume and improves the document, because the failure of large architecture documents is not inaccuracy but that the useful ten pages are unfindable inside the other forty.

Documentation should be sized to the number of readers, not to the size of the system.