Every team I have joined has the same complaint about its docs: they are out of date. The usual fix is a ritual — a "docs day," a linter, a PR checkbox that says "updated README." It never holds. Six weeks later the README lies again and everyone shrugs.
The problem is rarely discipline. It is that we keep putting the wrong kind of information in the README and expecting it to survive.
The README documents the wrong tense
A README is written in the present tense. "The service reads from Postgres." "Run the tests with npm test." "Auth goes through the gateway." Present tense is a claim about how the system is right now, and right now changes on every merge.
That makes the README a maintenance liability by construction. It is coupled to the implementation, so it inherits the implementation's churn — but nothing enforces the coupling. Code that drifts from the README does not fail to compile. No pipeline flags the sentence that stopped being true. The npm test line that points at a script nobody ever added will sit there for a year, and the only cost is a new hire losing an afternoon.
So the README does not decay gradually. It decays silently, and then all at once: the first line a reader catches being wrong poisons their trust in every other line. A document that is 90% accurate and 10% wrong, with no way to tell which is which, is worse than no document. It sends people looking for the truth with false confidence.
ADRs age into history instead of going wrong
An Architecture Decision Record is written in the past tense about a specific moment. "On this date, given these constraints, we chose Postgres over DynamoDB because X, accepting trade-off Y." It is scoped to one decision and stamped with the context that produced it.
That single change — past tense, dated, decision-scoped — is what makes it durable. When the decision reverses, you do not edit the old ADR into correctness. You write a new one that supersedes it and say why the context changed. The old record is not wrong. It is history. It still accurately describes what was true and what you knew when you decided.
A README goes stale because reality moved and the document stayed. An ADR cannot go stale in that sense, because it was never a claim about the present. It is append-only by nature, and append-only documents do not rot — they accumulate.
Where the two diverge
| README | ADR | |
|---|---|---|
| Tense | Present ("how it works now") | Past ("what we decided, and why") |
| Scope | The whole system, loosely | One decision |
| Update model | Edit in place, hope someone remembers | Append a new record, supersede the old |
| Coupled to | Implementation (high churn) | Decisions (low churn) |
| Failure mode | Silently wrong, no signal | Superseded, but still accurate as history |
| What kills it | Any merge that touches behavior | Nothing — you add, you never rewrite |
The row that matters is the last one. You can only keep a document current if the thing it tracks changes slowly. Decisions change far less often than code. Betting your documentation on the slow-moving thing is the whole trick.
What actually belongs in each
The mistake is treating the README as the home for everything: setup, architecture, rationale, roadmap, the reason you picked the queue. That is durable reasoning poured into a volatile container, and it is exactly the content that turns into a lie first, because "why we chose Kafka" outlives forty commits that quietly change how the system behaves.
Keep the README to the small set of things that both change rarely and can be verified. How to run it. Where the main pieces live. How to get a dev environment up. If a line in the README can be executed in CI, CI will tell you when it goes stale — and anything in there that cannot be checked by a machine, assume is already wrong.
Everything that answers "why" goes in an ADR. The database choice, the boundary you drew, the thing you deliberately did not build. That is the content people actually come back for six months later, and it is the content the README is worst at keeping alive.
The rule I use
Default to an ADR for anything you would be annoyed to re-derive from a Slack thread in a year. Keep the README to a quickstart you could hand a machine to verify. When you catch the README lying, that is usually a signal the sentence was reasoning that should have been an ADR in the first place — move it, do not just patch it.
Docs do not go stale because people are lazy. They go stale because we keep writing history in a document that is only allowed to talk about the present.