Writing Architecture Decision Records That New Engineers Can Actually Follow

A new senior engineer joins your team on a Tuesday. By Thursday, they are staring at a piece of infrastructure that seems needlessly complex: a verbose idempotency layer in the payments service, or a bespoke event bus where a standard queue would do.

They do the right thing. They look for the documentation. They find an Architecture Decision Record (ADR) from two years ago.

The ADR says the team chose this specific architecture. It lists the people who were in the meeting. It records the consensus.

It does not say why. It does not mention the Black Friday incident that triggered the change. It does not explain why the obvious, simpler alternative was rejected. The new engineer, seeing a complex solution with no apparent justification, refactors it into something cleaner. Nine days later, the system fails under load in exactly the way the original design was built to prevent.

An ADR that only records a decision is just a meeting note. A followable ADR is a mechanism for time travel: it allows someone who wasn't in the room to reconstruct the exact constraints that forced your hand.

What Separates a Decision From a Meeting Note

The difference between an ADR that works and one that fails is whether it documents the reasoning or just the result.

Bad ADRs document consensus. They read like a receipt of a conversation that already happened. They assume the reader shares the author's mental model, which is a safe assumption on the day it is written and a dangerous one six months later.

Good ADRs answer a specific set of questions. What did we decide? Why did we decide it? What else did we consider? What would make us revisit this?

When contributors to a software project leave, the knowledge they hold evaporates (research on this is consistent and unsurprising). The team lacking the knowledge is left guessing. The goal of an ADR is not to prove you made a decision. It is to prevent the next engineer from having to guess why you made it.

The Anatomy of an Answer That Lasts

You need a concrete structural template. Not a rigid form to fill out, but a baseline that forces the right information onto the page.

Start with a title specific enough to be searchable. "ADR-042: Database Selection" is useless. "ADR-042: Postgres for User Authentication Data" is better. Pair it with a status field: proposed, accepted, deprecated, or superseded. An ADR is never deleted. When a decision changes, you write a new record and link it to the old one (Microsoft's Well-Architected guidance is firm on this point). The history of how a system evolved is often as important as its current state.

The context section is where most ADRs fail before they even get to the decision. It should describe the problem, the constraints, and the current state of the world. Not in vague terms, but specifically: what was the team size, what was the budget, what was the timeline, what was the existing tooling. The reader needs enough information to understand why the decision was made, not just what it was.

The decision itself should be stated in active voice. "We will use Postgres for all user authentication data." Clear enough that someone can implement it.

Then comes the section that most ADRs skip and most new engineers need: alternatives considered. This is where institutional knowledge lives. If you do not document why you rejected the obvious alternative, the next engineer will propose it again. The conversation will restart from zero. The ADR that records the rejected path is worth more than the one that only records the chosen one.

Finally, consequences and revisit conditions. What does this decision make easier? What does it make harder? And critically: what would make you reconsider it? Scale thresholds, changes in vendor pricing, a shift in team size. If you don't write down the conditions under which the decision should be revisited, it will either be revisited constantly or never.

Writing Context That Doesn't Rot

This is the hardest part. ADRs rot because context rots.

You write an ADR assuming the reader knows that your team only had three backend engineers at the time, or that the budget was frozen, or that a specific vendor's API was notoriously flaky. Two years later, the team is twenty people, the budget is loose, and the vendor fixed their API. The decision looks absurd.

To write context that ages well, you have to document the constraints that mattered. Name the budget. Name the timeline. Name the team size.

Explain the problem in terms that make sense outside your current quarter's priorities. Link to external references (RFCs, research papers, vendor documentation) so future readers can verify your claims. Avoid jargon that only makes sense to your current team.

You are writing for someone joining the team in two years. They need to understand both the decision and the situation that produced it.

The Threshold for Writing It Down

Engineers often struggle with the threshold question. Does this decision need an ADR, or is it just a PR comment?

The heuristic is blast radius. Write an ADR when the decision has a significant blast radius.

If reversing the decision would require rearchitecting multiple systems, migrating data, or retraining a team, it needs an ADR. Choosing a database needs an ADR. Defining service boundaries in a microservices architecture needs an ADR. Selecting an authentication model needs an ADR.

If reversing the decision takes an afternoon, it doesn't. Naming conventions for variables, folder structures within a single service, or linter rules do not need ADRs.

Making the Archive Actually Useful

An ADR that no one can find might as well not exist. You have to make them part of the workflow, not an artifact buried in a wiki.

Store ADRs in version control, in the same repository as the code they govern (this is the consensus across teams that have made ADRs stick). This keeps them close to the implementation and allows them to be reviewed like code. Use a consistent naming convention (something like ADR-001-service-mesh-adoption.md) and maintain an index file at the top of the directory.

Link to relevant ADRs in PR descriptions when implementing the decision. Reference them in onboarding documentation. When someone asks, "why did we do it this way," the answer should be a link, not a thirty-minute conversation with the one engineer who was there.

Institutional memory is fragile. It is only as good as what survives when the people who built the system leave the building.

This is an operational problem, not just a writing problem. The discipline of writing good ADRs is real work, and it tends to collapse under schedule pressure unless there is a system that reduces the friction of capture.

Doc Holiday handles the initial synthesis: it pulls from code commits, pull requests, and release activity to generate documentation drafts. But the operative word is drafts. A senior engineer must actively review, validate, and approve every output before it becomes part of the team's architectural record. That review step is not optional overhead. It is the mechanism that keeps the documentation accurate and trustworthy. Without it, you have fast documentation that may be wrong, which is arguably worse than slow documentation that is right.

What Doc Holiday eliminates is the grunt work of starting from a blank page and manually tracking every decision across every PR. What it does not eliminate is the experienced judgment required to confirm that the synthesized output reflects what the team actually decided, and why. The goal is human-supervised automation: faster capture, with a senior engineer as the final authority on what gets committed to memory.

Because when the new engineer arrives on Tuesday, you want them reading constraints that a senior engineer has signed off on, not an unreviewed draft that happened to get merged.