Documentation Half-Life

Documentation rots 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 has a half-life of a few months: the structure changes weekly, and the document changes when someone is shamed into it.

Why it matters

The failure of large architecture documents is not usually inaccuracy. It is that the ten useful pages become unfindable inside the other forty, so readers stop looking — and once they stop looking, accuracy stops mattering and the decay accelerates.

Implementation patterns

Artefacts with a long half-life:

• Decision records. An ADR is never stale because it was always historical: context, options considered, the decision, the consequences, at a date. Highest value per word of any architecture artefact.
• A context diagram — the system, its users, its external dependencies. Changes a few times a year and is what new joiners, security reviewers and auditors actually need.
• Rationale that the code cannot carry: why the trading path has its own datastore, why this queue is deliberately not Kafka, which specific failure the odd-looking retry policy prevents.
• Anything generated from source, which cannot drift by construction.

Artefacts with a short half-life: component diagrams below the container level, class descriptions, narrative overviews of current structure, and anything a code reader could derive.

Industry example

A developer-tools company such as Postman, shipping continuously across many surfaces, cannot maintain a current-state document — and does not need to. What its engineers actually need is the reasoning: why collections sync the way they do, why the conflict policy is what it is, which failure the workspace-scoped cache exists to prevent. That content is stable for years, because reasoning outlives structure.

Failure scenarios

• The annual documentation refresh, which produces accuracy for a fortnight and then resumes decaying.
• Diagrams maintained by hand below the container level, which are wrong within a sprint and worse than absent because they are trusted.
• Documentation nobody can locate, which is functionally equivalent to none.
• Duplication between the document and the code, guaranteeing eventual disagreement with no signal about which is right.

Trade-offs

Generating documentation from source guarantees freshness and loses intent — generated diagrams show what exists, never why. Hand-written rationale carries intent and risks going stale.

The resolution is a division of labour: generate the structure, write the rationale. Then apply the filter to everything else — who reads this, when, and what decision does it change? Pages with no answer get deleted, which typically removes most of the volume and improves the document.

Interview question

"Your architecture documentation is eight months stale. You have two days. What do you write, what do you delete, and what do you automate — and how do you make sure it is not stale again in eight months?"