Most architecture documents are fiction. Not malicious fiction â nobody is lying to you on purpose â but fiction all the same: a confident narrative about a system that stopped matching reality somewhere between the approval meeting and the next reorg. The code, meanwhile, tells the truth every single day. It may be ugly, badly organized, commented in a dead language, but it is the only artifact in your company that cannot lie about what the system does. Which raises an uncomfortable question about why we keep producing forty-page PDFs describing it.
I have read a lot of these documents. In postmortems, in onboarding folders, in the quiet despair of a wiki nobody visits. The worst one I owned described a payments queue that was decommissioned before I was hired; two cohorts of new engineers learned about a service that never existed. The pattern is consistent enough to be boring: the document is a snapshot of intent, taken at the moment the author needed approval, and never updated again. Everything after that snapshot is a story the code writes without the author.
The document has no write path
State the core mechanic bluntly: code has a write path, and documents don’t. Code gets merged several times a day. Every pull request, every hotfix, every 2 a.m. hack rewrites the source of truth. The document’s write path ran exactly once, on approval day, and was then decommissioned. What you are left holding is a cache entry with no TTL, no expiry check, and no owner. It serves stale data with total confidence until somebody trusts it at the worst possible moment.
This is a race condition between two artifacts that are supposed to agree. One commits a hundred times a week. The other last wrote to disk in 2022. Guess which one wins.
Nobody notices, because nothing depends on the document. Dead code at least gets flagged by a linter or deleted in a cleanup sprint. Dead documents get bookmarked. They sit in the onboarding folder with the institutional equivalent of a verified badge: a senior engineer linked to it once, so it must be true.
What the document actually records
Read a stale architecture document carefully and you notice it was never really about the system. It is about the meeting. It records what the author needed to say to get the design through review: the tradeoffs that convinced the room, the boxes that looked tidy on a slide, the org chart as it existed that quarter. A transcript of a social ritual, typeset in a diagramming tool.
This is why reorgs kill these documents so reliably. The doc captures Conway’s law as it stood at approval time. Two reorgs later, the platform team it references has been split, merged, renamed, and split again. The document is now alternate-history fiction about an organization that no longer exists, while the actual system has quietly reshaped itself around the new org, with nobody writing any of it down. It has become a legacy system without the one decency legacy systems offer, which is that they still run.
Four operational signals your docs are fiction
You don’t have to audit the wiki to diagnose this. Like most organizational failures, stale documentation shows up in operational exhaust â the signals your team produces anyway, without meaning to. Four of them, roughly in the order they surface.
New hires route their questions around the documentation
Watch where a new engineer’s questions actually go. If the onboarding doc were load-bearing, the questions would thin out after week two. They don’t. They route to the same two senior engineers, every cohort, forever: âwho owns this service,â âwhy is there a second checkout path,â âis that diagram current.â The last one is the tell. When people ask whether a document is true before they are willing to read it, the document has already failed. Those two seniors are doing the documentation’s job by hand, in interrupt-driven mode. If you want the longer version: onboarding questions are a systems signal, not a people problem.
During incidents, nobody opens the doc
Incident response is documentation’s honesty test. At 2 a.m. with a customer-facing outage, people reach for whatever has the shortest path to the truth: dashboards, logs, git blame, the person who wrote the code. If the architecture overview or the runbook gets opened at all, watch what happens next. Do responders act on it, or do they open it, grimace, and keep scrolling? Opening a stale runbook mid-incident is a blocking call that returns the wrong answer and charges you for the latency. It burns the one resource you cannot recover mid-incident: attention.
Doc edit dates lag code churn by years
This one you can measure in an afternoon. Take your five most-linked documents and compare the last substantive edit date against the commit rate of the services they describe. A document last touched in March, describing a service that has taken four hundred commits since, is fiction with a header image. The gap between those two numbers is your documentation debt. Unlike technical debt, nobody has built a dashboard for it, so it compounds quietly.
A recurring meeting exists to explain the architecture
The monthly architecture walkthrough is not a knowledge-sharing initiative. It is a compensating control for a dead write path. The system’s description lives in one person’s head, and the meeting is the cron job that re-renders it for an audience. It works, mostly, the way manual retry loops work â until the person with the architecture in their head is on vacation during an incident and everyone discovers the wiki page was a placeholder. Recurring meetings are compensating controls more often than anyone admits; this is one of the textbook cases.
Root cause: the document’s only consumer was the approval
Run this like a postmortem and the root cause is almost embarrassingly simple. Architecture documents are approval artifacts. Their entire consumer base is one meeting that happens once. After approval, the document has no readers with the power to change it, no owner accountable for it, and no trigger that fires when the system it describes gets rewritten. A component with no consumers, no owner, and no alerts doesn’t stay accurate out of spite. It rots, the way anything unowned rots.
Contributing factors, in the usual style: updating the doc helps a future teammate nobody has met, while skipping it costs nothing today. The author has since moved to another team, where they are currently writing a new document that will also be true for about six weeks. And nothing in any feedback loop â the review, the retro, the ops review â notices the gap, because the gap has no metric. This is not a character flaw. Teams skip documentation maintenance for the same reason they skip any maintenance: unowned things rot, and nobody gets paged when they do.
What a document is actually worth
The what belongs to the code. The why is the only thing worth writing down. Code answers what the system does with total fidelity and zero context. It can’t tell you why the alternative was rejected, which invariants are load-bearing and which behaviors are incidental scar tissue from a 2019 incident, or which parts of the design are deliberate and which are leftovers nobody dared to delete. That information exists in exactly three places: the heads of people who were there, old pull request threads, and nowhere. Documents that capture the why survive contact with change. Documents that duplicate the what get outcompeted by git blame and die quietly.
So the fix is not âupdate the wiki more,â whatever the consultant deck says. The fix is to stop writing documents that describe the system and start writing documents that record decisions.
Architecture decision records are the boring, durable version of this. One page per decision: context, options considered, what we chose, what we expect to regret. Michael Nygard’s short 2011 note on documenting architecture decisions is still the best thing written on the subject, and it is shorter than most design review agendas. Each record is immutable, so it cannot drift â it can only be superseded by a newer record, which leaves a visible trail. You get a git history for reasoning instead of a PDF that gets quietly rewritten until it means nothing.
For the parts that genuinely need describing â system context, trust boundaries â keep it small. Simon Brown’s C4 model is the sane version: one context diagram, maybe one container diagram, then stop. Anything more detailed is a re-implementation of the codebase in a diagramming tool, and the codebase wins that race every time, because it has a write path and the drawing doesn’t. Google’s public write-up of its design doc practice lands the same point from the other end: the document exists to align people and record reasoning, not to mirror the code.
If you insist on keeping documents, treat them like systems
Short list, deliberately. Everything on it is a mechanism, not an exhortation.
- Every document gets an owner and a last-reviewed date. In the header, not in metadata nobody renders. A page without those two fields is an unowned service, and you already know what happens to those.
- Somebody owns the kill switch. When a pull request moves a trust boundary or splits a service, the review checklist asks which document it just made wrong. One question, asked at the moment the ground truth moves.
- Supersede, don’t edit. Rewriting history inside a doc is how you get fiction with a fresh timestamp. Mark the old decision superseded and link the new one.
- Review docs where you review ops. The quarterly review that already looks at deployment frequency and incident load can spend ten minutes on documentation freshness. Same lens, same meeting, no new ritual.
- Delete more than you update. A dead document that admits it is dead is harmless. A dead document with confidence is the expensive one.
Frequently Asked Questions
Why do architecture documents become fiction so quickly?
Because their write path runs exactly once, at approval, while the code they describe commits daily. With no owner, no expiry trigger, and no review cadence, every document starts drifting the moment the first post-approval pull request lands. It isn’t carelessness. It is a system with no feedback loop.
What should an architecture document contain instead of system descriptions?
Decisions, rejected alternatives, invariants, and constraints â the why the code cannot express. Record what you chose, what you turned down, and what you expect to regret. Topology, sequence flows, and component inventories belong to the code, or to diagrams you can re-render from it. Anything maintained by hand that a repository can tell you is a second source of truth, and second sources of truth always diverge.
How can I tell if my team’s documentation is fiction?
Check the operational signals before reading a word: where new hires route their questions, whether incident responders open the runbook and act on it, the gap between each document’s last edit date and the commit rate of the services it describes, and whether a recurring meeting exists to explain the architecture the docs were supposed to cover. If two or more of those look bad, the docs are fiction regardless of how good the prose is.
Are architecture decision records worth the overhead?
Yes, mostly because the overhead is one page per decision and the alternative is expensive. The cost lands at the moment you are already thinking hard about the decision anyway. The payoff shows up years later, when somebody asks why the system looks like this and the answer is a document instead of an archaeology dig through closed pull requests and whoever is still around to remember.
The uncomfortable summary
Your architecture document was a true story once, on the afternoon it was approved. Everything since has been the code changing and the document declining to notice. Stop asking teams to maintain descriptions the code maintains better, and spend the writing effort where the code cannot go: decisions, rejections, reasons. That part earns its bytes. The rest was always worth less than the code, and pretending otherwise is how the wiki got this bad.
