Did You Know? Architecture Decision Records
A constant bugbear throughout my career has been documentation. What do we document, who is it for, where do we keep it, how often is it updated? Approaches vary from organisation to organisation, and it often falls by the wayside when deadlines loom. I found myself always reaching for a quick and easy way to document important project decisions, so that I wouldn't be left scratching my head months later wondering why we did it that way.
And it turns out that there is a way - Architecture Decision Records.
What are they?
Architecture Decision Records (ADR) are actually a surprisingly simple solution to a common problem in software development. They are a short formal record of architecture decisions made for a software development project. This could be the choice to use one package over another, or a feature scoped down due to technical limitations. They can even be used more broadly to document project decisions, like deferring a feature due to time constraints.
The specific details recorded can depend on the organisation, the size of the project etc. but the important thing is recording the decision, the context and constraints around it, and the consequences.
What are they for?
Their core purpose is to record the context and consequences of important architecture decisions about a project. It answers the question "why did we do it this way?", but also "what happened next?".
We're not trying to understand decisions made months or even years before, when the original authors have moved on. We're not rehashing debates we've already had. We have a clear record of the trade-offs we considered, and can judge whether they're still relevant now. Can we now pick up that feature that was parked waiting on a package update? Can we replace that clunky workaround that was supposed to be only temporary?
And just as important, we can see the consequences of those decisions, and use them to better inform future choices. As with most documentation, we're building a project that outlasts us.
How to Use Them
They're refreshingly simple, which is why I'm still flabbergasted I'd never heard of them before now.
Each ADR lives as a short, numbered record, one decision in each one, with a descriptive title. A handful of fields hold the important details.
Status - usually something like proposed, accepted, or superseded. Most important in a team where you aren't solely responsible for the decisions needing made.
Context - the situation as it stood at the time. Any constraints that could affect the decision, whether these were technical, logistical, or even broader business or client constraints.
Decision - what was actually decided.
Consequences - what the decision costs, and anything you're accepting as a trade-off. This field is where a lot of value lies for future planning.
Some teams add more - alternatives considered and why they were rejected, who was involved, links to related ADRs, dates. The size of your team, the responsibilities and accountability they have, any standards the business aligns with, may require additional fields, but the four above do the heavy lifting.
Where you keep them isn't important, as long as it's a consistent, centralised place that everyone knows to check. A folder in the repository, or in whatever documentation tool you use. If you're also documenting broader project decisions, make sure the people who need to know can find it!
How does this benefit you?
If you've read my thoughts on building a portfolio, I talked about how difficult it is to demonstrate engineering thinking in code. A finished feature shows what you built. It doesn't show why you built it that way, what else you considered, or what you deliberately left out.
This is where a simplified version of ADR can still be useful, even on a project where you're the only person who'll ever read it.
Most of what's in a full ADR exists for a team's benefit. Status matters when someone else needs to know if a decision is still under discussion. Who was involved matters when there's more than one person to ask. On a solo project there's no one to update and no one to consult.
Context, decision, and consequences. The restrictions you faced (even if self-imposed), the decisions you made, and the effect it had on the outcome of the project.
In my own project, I recorded a decision to defer image performance optimisation to keep momentum, rather than stalling while I figured out the best way to do it in a new language framework. That one line showed that I knew of its importance to the user experience, and made a deliberate decision to come back to it after I had a complete feature to refine. A far better alternative than simply omitting it, or leaving a feature half-finished while I tried to find the "perfect" solution.
When I discovered ADR, it was a revelation. It was the solution I didn't know I was looking for, and strangely few people seem to know about it. I mentioned it to a few colleagues along the way, and most had never come across it either. It barely gets a mention in most of the Agile literature.
Did you know about Architecture Decision Records? Have you been reaching for a solution to documentation woes?
What's a technique or skill you found genuinely useful that hardly anyone around you seemed to know about? Share it in the comments.