Architecture Decision Records: Documentation That Isn’t Evil

Back in 2018, I asked whether documentation was the great evil. My answer was “maybe, but it doesn’t have to be.” Good documentation, I argued, is small, useful, and built into the way you already work.

If I were writing that post today, I’d spend most of it on one practice: the Architecture Decision Record, or ADR.

What an ADR is

The idea comes from Michael Nygard’s 2011 post, Documenting Architecture Decisions, and it’s almost embarrassingly simple. Every time your team makes a significant architectural decision, you write a short document, usually a page or less, that records:

Title. A short name for the decision. “Use PostgreSQL for the order service.”
Status. Proposed, accepted, deprecated, or superseded.
Context. What situation forced the decision? What constraints, requirements, and forces were in play?
Decision. What did you decide? Stated plainly.
Consequences. What gets easier because of this decision, what gets harder, and what you’re accepting as a trade-off.

That’s it. You store them in the code repository next to the code they describe, number them in order, and never delete them. When a decision changes, you write a new ADR that supersedes the old one.

Why it works

ADRs succeed where most architecture documentation fails, for a few reasons:

They’re small. One decision, one page. It takes 20 or 30 minutes to write, which is about the same budget I argued for in the original documentation post.
They capture the why. Code tells you what the system does. Diagrams tell you how it’s structured. Almost nothing tells you why it’s that way, and the why is what new team members, auditors, and your future self need most.
They don’t go stale. Most documentation is a description of the current state, so it starts to rot the moment the system changes. An ADR describes a decision at a point in time. It stays true even after it’s superseded, because it records what you decided and why, then.
They live with the code. No file share, no wiki nobody visits. They’re reviewed in the same pull requests and versioned in the same history.
They slow you down just enough. Writing down the context and consequences forces you to think about them. More than one “obvious” decision has fallen apart halfway through its own ADR.

How ADRs fight complexity

This is the part that matters most for this blog. ADRs are one of the best tools I know for keeping complexity in check.

They make complexity spending visible. Every new database, framework, or integration pattern should come with an ADR. Suddenly you can see your complexity budget being spent, one decision at a time, with a reason attached.

They stop the same argument from coming back. How many hours has your team spent re-debating a decision made two years ago because nobody remembered why it was made? With an ADR, the conversation starts at “here’s what we knew then; has anything changed?”

They make subtraction safer. Chesterton’s Fence says don’t remove something until you know why it’s there. ADRs are the note left on the fence.

They pair well with AI-assisted development. When a growing share of code is written by AI tools, recording the human reasoning behind the architecture becomes more important. An ADR is also great context to give those tools, so they follow your decisions instead of quietly overriding them.

Getting started

Don’t turn this into a program. That’s how good ideas become evil documentation. Instead:

Create a docs/adr folder in one repository.
Write ADR 0001: “Record architecture decisions.” (Yes, the first decision is to start recording decisions. It’s tradition.)
Write the next one the next time your team makes a decision someone might later ask “why?” about.
Review ADRs in pull requests like any other change.

If you want templates and tools, adr.github.io has a good collection. But honestly, a Markdown file with five headings is all you need.

So, is documentation evil? Not this kind. This kind might be the most useful half hour your team spends all week.