Every architecture document you have inherited is out of date. How do you write documentation that survives contact with a changing system?

Documentation does not rot uniformly

The instinct on inheriting a stale wiki is to schedule a documentation sprint, and that instinct is wrong because it treats the symptom. Some documentation goes stale within a week and some is still correct a decade later, and the difference is systematic rather than a matter of discipline.

A list of the services in a system is stale by the next deployment. A sequence diagram of a specific API call is stale by the next refactor. But a record saying in March 2024 we chose Postgres over DynamoDB because our access patterns were relational and the team had no operational experience with DynamoDB is still accurate in 2030, because it is a statement about a decision that was made, not about a system that has since changed.

So the strategy is not to write more or to write better. It is to stop writing down the things that decay, and to write down the things that cannot.

Three categories, three different treatments

Decisions and their rationale are written by hand and never edited. This is the ADR, and its value is entirely in the "why": the options considered, the constraints at the time, the thing you were worried about. Code shows what you chose. Nothing except the ADR shows what you rejected and on what grounds, and that is exactly what the next person needs before they overturn it.

Structure should be generated wherever it can be. The service list, the dependency graph, the API surface, the database schema — all of these exist already in a form a machine can read, and a hand-drawn copy of them is a second source of truth that will disagree with the first. Where generation is not practical, keep the diagram at a level of abstraction that changes slowly. A C4 context diagram showing four systems and the users around them may not need revising for years; a component diagram of one service's internals will be wrong within a quarter, which is a reason to draw it for a specific conversation and then throw it away rather than to enshrine it.

Orientation is the thing new joiners actually need and the thing least often written: what this system is for, which parts are load-bearing, where the bodies are buried, what will surprise you. It changes slowly, it cannot be generated, and it is worth an afternoon of someone senior's time.

An ADR is an append-only log

The most common way a decision record fails is being treated as a page. Someone reverses the decision, opens the original, and edits it — and the reasoning that led to the original choice, which is the only reason the file existed, is now gone.

Write a new record instead. Mark the old one superseded with a link forward, and leave every word of it intact. The pair is worth more than either alone, because the interesting artefact is not "we use Kafka" but "we chose Kafka for these reasons, and eighteen months later those reasons stopped holding for this specific one". That is the institutional memory that stops a team relitigating the same argument every two years, and it only exists if the losing side of the argument stays on the record.

Keeping records short helps them get written at all. Context, decision, consequences, on one page. A template demanding a dozen sections produces no ADRs, and no ADRs is a considerably worse outcome than terse ones.

Put the documentation where the change happens

Documentation maintained in a separate tool from the code is maintained on separate goodwill, and goodwill is not a mechanism. Markdown in the repository, changed in the same pull request as the code, reviewed by the same reviewer, is the only arrangement that reliably works — not because engineers prefer Markdown but because it makes the documentation update visible to someone who can notice its absence.

This is also the honest answer to "how do you make people write it". You mostly cannot, through exhortation. You can make the missing update show up in a diff where a reviewer will ask about it.

Decide what not to document

A documentation set that aspires to completeness fails, and it fails in the worst way: partially, so readers cannot tell which pages are current. A smaller set that is trusted beats a comprehensive one that is not, because the failure mode of trusted-but-incomplete is a question asked in Slack, while the failure mode of comprehensive-but-unreliable is a decision made on false information.

So say out loud what you are not documenting and why. Internal class structure, because the code is the truth and reading it is fast. Individual endpoint behaviour, because the generated API reference covers it. Anything with an owner who will answer in five minutes. Being explicit about the gaps is what makes the rest credible.

Write down what you decided and why you decided it. Generate what the code already knows. Be honest about what you have chosen not to write at all.