I’ve watched more systems die from lousy documentation than from lousy code. That’s not a metaphor. That’s a body count. A perfectly decent architecture—one that could have scaled, could have been maintained, could have made the company actual money—gets gutted because nobody wrote down why it was built that way. Six months later, a new hire with a messiah complex rewrites the whole thing in a weekend hackathon, and suddenly your pager is screaming at 3 a.m.
Here’s the ugly truth: an architecture decision without a written record is just a rumor. It spreads, mutates, and eventually becomes the thing everyone curses at but nobody understands. If you’re not documenting your architectural choices, you’re not engineering. You’re just decorating a house of cards.
The Half-Life of an Undocumented Decision
Let’s talk about decay. Not bit rot—decision rot. You make a call in a meeting: “We’re going with a modular monolith instead of microservices because our team is five people and our latency budget is tighter than a hipster’s jeans.” Everyone nods. Two people leave. Three new people join. The original Slack thread scrolls off into the void. Now that decision exists only as a vague tribal memory, and the new folks are already drafting a proposal to “fix” the monolith by splitting it into 47 nanoservices.
This isn’t a people problem. It’s a culture problem wearing a technical mask. The engineering culture that treats documentation as an afterthought is the same culture that will burn three sprints rewriting a service that was built in three days, all because nobody understood the original constraints. You’re not saving time by skipping the write-up. You’re borrowing time at loan-shark interest rates.
Documentation Is Not a Novel
Let’s kill a sacred cow right now: nobody wants to read your 40-page architecture manifesto. That’s not documentation. That’s a cry for help. Good architecture documentation is a decision log, not a dissertation. It answers five questions and then gets out of the way:
- What did we decide?
- Why did we decide it? (Context, constraints, trade-offs)
- What alternatives did we reject and why?
- When did we decide it? (Date, people in the room)
- What are the known consequences or risks?
That’s it. If you can’t fit it on a single page, you’re not documenting a decision. You’re writing a memoir. Stop it.
I once walked into a codebase where the “architecture doc” was a 60-page Google Doc with 147 unresolved comments. The team had been arguing about it for eight months. The system itself had been in production for two years. The doc was a fossilized argument, not a guide. Nobody read it. Everyone just asked Dave. Then Dave quit. Then everyone panicked.
The Real Cost of Missing Context
When a new developer opens a pull request that casually proposes replacing your hand-rolled caching layer with Redis, they’re not being stupid. They’re operating with the information they have. They see a custom solution and think “legacy cruft.” They don’t know that you tried Redis three years ago and it fell over under peak load because of a kernel bug that only triggered with your specific access pattern. They don’t know that the hand-rolled layer has 18 months of tuning for your exact workload. They don’t know because nobody wrote it down.
So you reject the PR. Maybe you leave a terse comment. The new developer feels dismissed. They start to believe the codebase is run by grumpy wizards who hate progress. Trust erodes. Six months later, they leave for a company that “embraces modern tools.” You lost a good engineer because you couldn’t be bothered to explain your past decisions. That’s not a retention problem. That’s a documentation problem wearing a hoodie.
Architecture Decision Records: The Antidote to Amnesia
If you’re not using Architecture Decision Records (ADRs), you’re doing oral history. And oral history is a terrible way to run a software project. ADRs are short, plain-text files stored in your repository, right next to the code they influence. They’re not wiki pages that rot in a separate system. They’re not Confluence documents that require a VPN, two-factor auth, and a blood sacrifice to access. They’re right there, in version control, evolving with the code.
An ADR has a title, a status (proposed, accepted, deprecated, superseded), a context section, a decision section, and a consequences section. That’s it. You write one when you make a significant architectural choice. You link to it from your code. When someone proposes a change that contradicts an existing ADR, they either write a new ADR that supersedes the old one or they have a very awkward conversation in the pull request comments.
This isn’t bureaucracy. This is engineering hygiene. You wouldn’t deploy code without tests. You shouldn’t deploy architecture without a record of why it exists.
What Qualifies as an Architecture Decision?
Not every choice needs an ADR. Choosing between tabs and spaces is a style guide issue, not an architecture decision. But if you’re picking a database, a messaging pattern, a deployment topology, or a significant library that shapes how the system behaves—write it down. If the decision affects more than one team, write it down. If the decision has a cost to reverse, write it down. If you’re choosing something unusual or counterintuitive, definitely write it down.
Here’s a rule of thumb: if you’d be annoyed explaining this decision for the third time to a new team member, it belongs in an ADR.
When Documentation Becomes a Weapon
I’ve seen teams use documentation as a political tool. They write overly detailed specs not to inform, but to constrain. They create processes that require sign-off from three architects and a security review before anyone can change a CSS file. That’s not documentation. That’s a power play with extra steps.
Good documentation empowers. Bad documentation controls. If your architecture docs are being used to say “no” more often than they’re used to say “here’s why we did this, now make it better,” you’ve built a bureaucracy, not a knowledge base. Burn it down.
I once consulted for a company where the “architecture review board” was just two senior engineers who hadn’t written production code in four years. They required a 20-page document for any new service. Teams started building shadow services to avoid the process. The official architecture was a fiction. The real architecture was whatever people could sneak past the gatekeepers. That’s what happens when documentation becomes a weapon.
Write for the Person Who Will Replace You
Here’s a mental exercise: imagine you win the lottery tomorrow and vanish. Who picks up your code? What do they need to know to not immediately hate you? Write for that person. Write with the assumption that the reader is smart, motivated, and completely ignorant of every conversation you’ve had for the last two years.
This means explaining why, not just what. A comment that says “// increment counter” is useless. A comment that says “// increment counter before the check to avoid a race condition with the cleanup job (see ADR-004)” is gold. The first is noise. The second is context. Context is what separates a codebase you can maintain from a codebase you flee.
And for the love of everything, date your decisions. Nothing is more infuriating than finding a document that says “We decided to use MySQL because it’s the best option available” with no date, no alternatives listed, and no mention of who “we” is. That document is worse than useless. It’s misleading. It implies a permanence that doesn’t exist in software.
The Half-Life of a Decision
Every architecture decision has an expiration date. It might be six months. It might be six years. But eventually, the context that made it right will change. Your monolith was the right call when you had three engineers and one product. Now you have forty engineers and seven products. The decision hasn’t aged well. That’s fine. That’s expected. What’s not fine is pretending the original decision is still valid without re-evaluating it.
Good documentation makes this re-evaluation possible. When you have a record of the original context, you can compare it to the current context and make a deliberate choice: keep the decision, modify it, or replace it. Without that record, you’re just guessing. You’re making decisions based on folklore and frustration.
I’ve seen teams spend months “modernizing” a system only to discover they’d recreated the exact problems the original architecture was designed to avoid. The original team had solved those problems through painful experience. But because nobody wrote it down, the new team had to learn the same lessons the hard way. That’s not iteration. That’s amnesia.
Documentation as a Hiring and Onboarding Tool
When a senior engineer interviews with your company, they’re not just evaluating your tech stack. They’re evaluating your engineering culture. And one of the fastest ways to signal that your culture is a mess is to have no coherent architecture documentation. It tells candidates: “We make decisions by vibe. We forget why we did things. You’ll spend your first six months reverse-engineering tribal knowledge from git blame and Slack logs.”
Good candidates have options. They’ll choose the company where they can read a few ADRs and understand the system’s evolution. They’ll choose the company where the architecture isn’t a secret society.
Onboarding is the same story. A new engineer with good documentation can be productive in days. Without it, they’re in a fog for months. That fog costs real money. It costs missed deadlines, bad decisions, and rework. If you’re not factoring documentation into your onboarding costs, your spreadsheets are lying to you.
When the Code Is the Documentation (and Why That’s a Lie)
There’s a certain breed of developer who says “the code is the documentation.” These people are either lying or have never maintained a system they didn’t write. Code tells you what and how. It does not tell you why. It does not tell you what was considered and rejected. It does not tell you about the meeting where three senior engineers screamed at each other for two hours before arriving at a compromise that looks simple in code but was born from blood and fire.
Code is a snapshot of the final state. It’s the last page of a novel. Architecture documentation is the plot summary. Without it, you’re trying to understand the story by reading the last page over and over.
What Happens When Documentation Is Actually Good
I’ve seen teams where architecture documentation is a first-class citizen. ADRs are in the repo. They’re linked from the code. They’re updated when decisions change. The result? Onboarding takes days, not months. Refactoring is informed, not reckless. Arguments about “why we did this” end with a link to a document, not a shouting match in Slack.
These teams aren’t staffed by superhumans. They’re staffed by engineers who understand that writing down why you did something is part of doing it. They treat documentation like tests: not optional, not an afterthought, but a core part of the deliverable.
And here’s the kicker: these teams move faster. They make better decisions. They have fewer incidents. Because they’re not constantly rediscovering their own history.
FAQ
How detailed should an architecture decision record be?
Short enough to read in five minutes, long enough to capture the context, decision, alternatives, and consequences. If you need diagrams, link to them. Don’t embed a novel. The goal is clarity, not completeness. A decision record that nobody reads is just as useless as no record at all.
What if we made a bad decision? Should we still document it?
Absolutely. In fact, bad decisions are the most important ones to document. Write down what you decided, why you thought it was right at the time, and what actually went wrong. That’s not a failure—it’s a vaccine. Future engineers will see it and avoid repeating the same mistake. If you bury it, you’re guaranteeing someone will make it again.
How do we convince management to invest time in architecture documentation?
Stop framing it as “documentation.” Frame it as “reducing onboarding time, preventing bad rewrites, and avoiding production incidents.” Then show them the math. A single avoided incident can save more engineering hours than a year of writing ADRs. If they still don’t get it, ask them how much they’d pay to have a record of every major decision made in the last two years. That’s what you’re offering to build going forward.
What’s the difference between architecture documentation and code comments?
Code comments explain the how and sometimes the why of a specific line or function. Architecture documentation explains the why of the system’s structure, the trade-offs, and the constraints that shaped it. Code comments are local. Architecture documentation is global. You need both, but they serve different purposes.
Stop treating architecture decisions like campfire stories. Write them down. Your future self—and every engineer who inherits your code—will thank you. Or at least they won’t curse your name in the middle of an outage. That’s the real win.
