Architecture Decision Record, or ADR for short, is a tool that will improve communication, increase transparency in your engineering department, foster collaboration, and make future maintenance easier. We at Supermetrics are using ADRs and have found these benefits for ourselves.
Having up-to-date and useful documentation is a constant struggle. It’s hard for software engineers to think about writing documentation when writing actual code is often more interesting. It’s even harder to keep that documentation up to date if there’s a production incident or a tight deadline for delivering a project. As a result, documentation might not exist or not be as useful as it could be. That’s where ADRs can be useful.
What is an Architecture Decision Record?
Simply put, an ADR is the sweet spot between having extensive, deep-dive documentation and no documentation at all. Think of it as minimal documentation that’s always up to date with just a little effort.
More specifically, an Architecture Decision Record is a document that captures the important decisions made during the development of any project. It’s about writing down your thoughts, the context around the changes you’re making, your assumptions at the time of writing, expected consequences, and the changes themselves. Michael Nygard coined the name ADR and created a handy template for creating them.
A template for ADRs
The original template, as suggested by Nygard, looks like this:
- Title - May include a sequential number and/or date.
- Status - The status of ADR, such as proposed, accepted, rejected, deprecated, or superseded.
- Context - An explanation of why the change is needed.
- Decision - A summary of the actual change being made.
- Consequences - The anticipated positive and negative consequences of the change.
At Supermetrics, we’ve decided to extend the template with a few more items:
- Impact - Will the change have a low/medium/high impact on the code base?
- Contributors - Who contributes to preparing, reviewing, and approving the ADR?
- Options considered - A summary of what other options were considered, if any.
- Outcome - What do we expect the end result to be when this decision is fully implemented?
- Metrics - How will we measure the success of this decision?
- Roll-out strategy - What’s the plan for releasing this change to users?
Each development team is welcome to customize the template if they find it limiting. When using an ADR template, customize it to fulfill your needs and cover your use case.
When to write an ADR?
If you made a code change but didn't document and communicate it properly, you can hardly expect your teammates to know about it or understand it. As short-form documentation, an ADR makes getting everyone on the same page easy. It creates a common understanding of new changes before they happen.
So, prepare an ADR before you make a change that impacts another part of the system or how code is written. As a bonus, it'll help reduce the number of different solutions for the same problem, which often result from undocumented changes.
Nothing stops you from going back to old changes and writing ADRs about them. It’s even recommended, especially when different developers repeatedly ask the same questions about a part of your system. Next time, you can refer them to the ADR.
Where and how to store ADRs?
The original idea by Nygard suggests you should use Markdown for easier formatting and reading and a git repository for storing the .md files themselves— ideally in the same repository as the code. At Supermetrics, we decided to keep ADRs in our wiki Confluence because we have multiple products and many repositories. It’s easier to find and read ADRs if they’re all in the same place, especially if individual ADRs affect multiple products.
Benefit #1: easier documentation maintenance
As you can see from the template, the final ADR isn’t going to be a very long document. Depending on your template, it could be from one to a few pages of text. Nor should it be highly abstract or require deep-dive knowledge to decipher. The ADR is supposed to be a simple document that gives concrete, practical information about how a change has been thought out and executed. It’s not about something abstract, or about explaining some architecture that requires deep dive knowledge. Writing down the context, decision, and consequences is straightforward enough since a developer has to consider them anyway when making changes to code.
An ADR explains the thinking behind a change at the time when the change was made. Once approved, its contents don't change much. Later, if you find out that you made a poor decision, or if the requirements of the decision (the context) change, you'll prepare a new ADR and deprecate or supersede the older one, changing only its status. The ADR releases you from maintaining old documentation. If something changes in the code, you’ll simply create a new ADR for the alterations.
You can compare an ADR to a blockchain, where only new pieces are added, and you need to go through the whole chain of records to understand the current state of the system.
Benefit #2 - Insight into the past
Understanding the why behind past software design decisions allows you to better understand their outcome. ADRs can help you with that. Traditional documentation typically explains how different parts of the software are connected and how they communicate. What it fails to explain is why something was done a certain way.
An ADR is a kind of a brain dump, covering the context of a change and its potential effects, and considering alternative options. So, when a new person joins the team and asks, "Did you consider X?" or "Why was it done this way?" they can go and read the ADR.
If you use an ADR throughout your projects for all meaningful changes, you’ll notice that it becomes a changelog and a single source of truth for your software. There’ll be less speculation about past changes and less knowledge lost between silos. ADRs also make code ownership a real thing, making project handovers and learning from past mistakes easier.
Benefit #3 - improved transparency, collaboration, and communication
The ADR template we use at Supermetrics includes a list of collaborators, which ensures that any planned changes are discussed between at least a few people, enforcing communication and collaboration. Teammates may have differing opinions about how to solve a problem, but collaborating on the ADR makes it easier to find common ground and choose the best solution. It also helps us see more of the potential consequences of implementing a change.
Listing contributors also makes it easy for developers to discuss past changes and their results with change authors and plan future changes that would supersede the old ones. Not knowing why something was done in the past makes future changes in the same area very risky, so that context should be written down in an ADR and made easily accessible to all developers.
ADRs make communication easier by improving transparency and collaboration within and between development teams. To make it even better, follow these steps:
- Use simple, easily understandable language in your ADRs.
- Skip details on technical implementation — those aren’t meant to be part of an ADR.
- Limit ADRs to a single decision or change.
No documentation is perfect
We think ADR is a good-enough form of documentation for architecture and software changes. While it’s not a silver bullet by any means, it’s simple to prepare and has great benefits. ADRs allow us to make decisions widely understandable within the Engineering team and course-correct later if needed while keeping a paper trail of all the changes.
These easy-to-read documents make it easier to onboard new developers to the inner workings of the system architecture and why it was built in a certain way.
Your turn
Give ADRs a try, and let us know what you think. Were they helpful? What information did you find essential to include in your ADR template? We’d love to learn from your experiences!
Learn more about how the Engineering team at Supermetrics works at supermetrics.com/careers/engineering.
Top comments (0)