Look, I’ve been around long enough to know most software architecture arguments are just theatre. You’ve got the whiteboard warriors sketching perfect hexagons while the rest of us wonder if they’ve ever actually deployed to production. But there’s one thing that separates the adults from the children in engineering, and it’s not your fancy event-sourcing pattern. It’s whether anyone—including you, six months from now—can figure out what the hell you were thinking.
Architecture decisions are social constructs. They’re bets we place with spotty information, and the only real currency is how well we communicate those bets. Without documentation that doesn’t make people want to bang their heads on the desk, your brilliant design is just a ghost haunting the codebase, scaring new hires and pushing senior engineers toward a drinking problem during on-call.
The Architecture Decision Record: Your New Best Friend
I’m not talking about that auto-generated wiki some intern set up three years ago and nobody’s touched since. I’m talking about Architecture Decision Records—ADRs—a practice that’s been around since Michael Nygard wrote about it in 2011. If you haven’t read his original post, stop everything and go find it. I’ll wait.
ADRs are like the medical charts of your system. They lay out the context, the decision, and the fallout. Not the marketing fluff, not the aspirational architecture diagram that looks like a subway map designed by a committee of unicorns. Just the cold truth: “We chose option X because option Y would’ve meant rewriting half the monolith, and Bob was on vacation.” That’s the kind of honesty that saves necks.
Here’s the thing about engineering culture: we’re obsessed with being right, but we’re allergic to being understood. We’ll burn three weeks arguing Kafka versus RabbitMQ, but we won’t spend three hours writing down why we picked one. Then six months later, someone new joins, stares at the mess, and kicks off a Slack thread that replays the entire debate from scratch. That’s not engineering; that’s Groundhog Day with more caffeine.
What an ADR Actually Looks Like
It’s not a novel. It’s not a design doc that tries to predict the next five years of product roadmap. A decent ADR has four parts:
- Title: A short name that doesn’t sound like a marketing bot spat it out. “ADR 001: We’re using PostgreSQL because we’re not insane” works fine.
- Context: What problem were we solving? What constraints were we under? Was the CTO breathing down our necks because he read some blog post about microservices? Write it down.
- Decision: What did we actually choose? Be specific. “We will use a relational database with read replicas” isn’t a decision; it’s a wish. “We will deploy PostgreSQL 14 on AWS RDS with at least two read replicas in us-east-1” is a decision.
- Consequences: What got better? What got worse? Did we trade consistency for availability? Did we make the frontend team cry? Own it.
That’s it. You can slap on a status and a date if you’re feeling fancy, but the core is four sections that force you to think like an adult. I’ve seen teams stick ADRs straight into their repo next to the code, using a simple markdown file. No special tools, no Confluence pages that need a VPN and a prayer to access. Just text files that survive reorgs and tooling migrations.
Why Most Documentation Fails (And It’s Mostly Your Fault)
Let’s be honest: most documentation is written for the wrong crowd. Engineers write docs for themselves, or for some mythical architect who’s going to review the system with a checklist. But the real audience is the poor soul who joins the team in two years, opens the repo, and has zero clue why there’s a Redis cluster that seems to do nothing but cache cat memes.
Documentation fails when it’s too generic. “We follow microservices best practices” isn’t documentation; it’s a LinkedIn post. It fails when it’s too detailed, describing every class and method as if the code itself didn’t exist. And it fails most spectacularly when it’s out of date, because nothing kills trust faster than a diagram showing services that were decomissioned during the Obama administration.
The fix is simple, but it demands a culture shift. You need to treat documentation as part of the architecture process, not an afterthought. When you make a significant decision—say, choosing a message broker or deciding to split a service—writing the ADR is part of the work. It’s not something you do on Friday afternoon when your brain is fried. It’s the thing you do before you start coding, because if you can’t explain the decision clearly, you probably don’t understand it yourself.
The Real Technical Problem Is Ego
Here’s where I get blunt. The biggest barrier to decent architecture documentation is the ego of senior engineers. We’ve all met that person—the one who designs a system in their head, bangs it out in a caffeine-fueled sprint, and then acts annoyed when anyone asks questions. “Read the code,” they say, as if the code is Tolstoy and not a pile of spaghetti held together by hope and a few integration tests.
That attitude is a liability. It creates knowledge silos that turn into bus factors. When that engineer leaves—and they will, probably for a job with better pay and better snacks—they take the architecture with them. The rest of the team is stuck with a system nobody understands, and you start seeing commits that just add comments like “// don’t touch this, it breaks everything.”
Good documentation is an act of professional humility. It says, “I made this decision with the information I had, and I’m writing it down so you can judge me later.” It’s the opposite of job security through obscurity. It’s also the only way to have honest technical discussions. When a decision is written down with its context and consequences, you can argue about the trade-offs instead of arguing about what someone remembers from a meeting six months ago.
From ADRs to Living Documentation
ADRs are just the start. Once you’ve got a habit of writing down decisions, you can build a lightweight documentation system that actually survives contact with reality. The key is to keep it close to the code and make it easy to update. I’ve seen teams use a /docs folder in the repo with a simple index, or a static site generator that pulls from markdown files. The tool doesn’t matter as much as the discipline.
One pattern I like is the “decision log” that’s part of the project’s README or a dedicated page. It lists every ADR with its status—proposed, accepted, superseded—so anyone can see the history of the system’s architecture at a glance. When a decision gets reversed or replaced, you don’t delete the old ADR; you mark it as superseded and link to the new one. That way, you’ve got a trail of how the thinking evolved, not just the final state.
This also helps with onboarding. Instead of handing new engineers a 50-page wiki that was last updated during the Trump administration, you hand them a list of decisions that explain why the system looks the way it does. They can read the ADRs, dig into the code, and actually get the trade-offs without having to corner a senior engineer in the kitchen and beg for context.
When Good Documentation Goes Bad
There’s a dark side to this, and I’ve seen it play out in teams that get too religious about documentation. You know the type: they turn ADRs into a bureaucratic process with templates, review boards, and a requirement that every decision be signed off by an “architecture council” that meets once a month and mostly argues about lunch orders. That’s not documentation; that’s performance art.
Documentation should be lightweight enough that it doesn’t feel like a chore. If writing an ADR takes more time than the decision itself, you’re doing it wrong. The goal is to capture the essence of the decision, not to produce a legal document you could submit as evidence in court. I’ve seen one-page ADRs that are more valuable than 30-page design docs because they actually get read and updated.
Another failure mode is documentation that’s too focused on the “what” and not the “why.” A diagram that shows service A calling service B is useless without context. Why does it call it synchronously? Why not use a queue? What were the latency requirements? The “why” is the part that ages well; the “what” is going to change next sprint anyway.
The Culture Shift Nobody Wants to Talk About
Here’s the uncomfortable truth: if your team doesn’t value documentation, it’s because your engineering culture has a problem. Not a tooling problem, not a process problem—a culture problem. Somewhere along the way, someone decided that writing things down is less important than shipping features, and now you’re paying the price in production incidents and wasted meetings.
Fixing this starts with leadership. If your tech lead or CTO doesn’t write ADRs and doesn’t ask for them, nobody else will. But it also requires a shift in how we evaluate engineering work. Right now, most performance reviews are based on code shipped, bugs fixed, features delivered. Nobody gets promoted for writing documentation that prevents a disaster two years later. That’s a failure of incentives, and it’s why most documentation is a wasteland.
I’ve seen one team experiment with making ADRs part of their definition of done. Before a story is complete, any significant architectural change had to have an ADR written and reviewed. It wasn’t heavy—just a quick check that the decision was documented. At first, people grumbled, but after a few months, it became a habit, and the team’s collective understanding of the system improved hugely. They spent less time in meetings explaining things and more time actually building.
What Happens When You Ignore This
Let me paint you a picture. You’re called into a production incident at 3 a.m. The database is melting, and nobody knows why. You trace the issue to a caching layer that was added two years ago by an engineer who’s now at a startup in Berlin. There’s no documentation, just a commit message that says “added cache.” The config is a mess of magic numbers, and nobody knows what happens if you tweak them. You spend four hours debugging, and by the time you fix it, you’ve lost a year of your life to stress.
That’s not a hypothetical. That’s a Tuesday in most engineering orgs. And it’s entirely preventable if someone had written down why the cache was added, what the eviction policy should be, and what the expected failure modes are. Instead, you’ve got a system held together by tribal knowledge and prayer.
The cost of bad documentation isn’t just the incident itself; it’s the slow erosion of trust in the system. Engineers start adding defensive code because they don’t understand the original intent. They duplicate functionality because they’re scared to modify existing components. The codebase becomes a museum of abandoned decisions, and nobody wants to be the curator.
FAQ: Because You Probably Still Have Excuses
“We’re too busy shipping features to write documentation.”
You’re too busy to save yourself time later? That’s like saying you’re too busy driving to change the oil. Documentation isn’t overhead; it’s an investment that pays off every time you avoid a redundant meeting or a production fire. If you’re constantly in crunch mode, that’s a sign your architecture is already a mess, and documentation is the first step to digging out.
“Our system changes too fast for documentation to keep up.”
Then your documentation is too detailed. Stop trying to document the current state of the code; document the decisions and the principles behind them. Principles don’t change every sprint, even if the implementation does. If your architecture is truly evolving that fast, ADRs for each significant change will actually help you track the evolution instead of losing the thread entirely.
“Nobody reads the documentation anyway.”
Nobody reads it because it’s useless. If your documentation is a graveyard of outdated PDFs and auto-generated nonsense, of course nobody reads it. But if you write ADRs that are concise, honest, and close to the code, people will read them—especially during incidents or onboarding. I’ve seen teams where new hires devour the ADR log because it’s the only thing that actually explains the system. Make it good, and they will come.
“Can’t we just use AI to generate documentation?”
No. Absolutely not. We’re not going there. Documentation is about human judgment and context, not about auto-generating paragraphs from code comments. If you’re relying on a tool to explain your decisions, you’ve already lost the plot.
The Bottom Line
Your architecture decisions are only as good as the documentation around them because architecture is a social activity. It’s about aligning a group of humans around a shared understanding of a system that’s too complex for any one person to hold in their head. Without that shared understanding, you don’t have an architecture; you have a collection of accidents held together by duct tape and hope.
So do yourself a favor. Next time you make a significant decision, write it down. Not in an email, not in a Slack thread that will vanish into the void, but in a file that lives with the code. Make it short, make it honest, and make it something your future self would thank you for. Because when the on-call pager goes off at 3 a.m., you’ll want to know why the hell someone chose that message queue, and you’ll want to know it fast.
Architecture isn’t about being right. It’s about being understood. And that starts with documentation that doesn’t treat your teammates like mind readers.
