fundamentals

Using Architectural Decision Records

ADRs are a powerful tool for understanding why decisions were made and reflect on if and when it’s appropriate to change them.

Britton Broderick

May 7, 2022 • 5 min read

Photo by Wesley Tingey on Unsplash

An Architectural Decision Record (ADR) is a historical record outlining why decisions were made. They also document tech and team norms as they are adopted.

They do not serve as documentation for code. That should live in the codebase itself, supported by documentation constructs provided by the language or supporting libraries.

Engineers introduced to a new codebase will ask why such a poor decision was made about a given feature. When revisiting part of the codebase years later you decide to rip out a piece you can’t see the value in, only to learn that it was critical when prod goes down later that day. You want to talk with the author of part of the codebase about why things are the way they are, only to learn they left the company years ago. Or they’re still around but have no idea why they did it that way, but they feel like it was important.

An ADR describes this while the information is fresh. You remember the context under which the decision was made, why it was made, because you’re here making it. It isn’t a poor decision or else you’d be making a different decision. When, in the future, circumstances have changed, it allows you to confidently change the decision made. See Chesterton's Fence.

Example

# 6. Packaging and distribution in other version control repositories

Date: 2016-02-16

## Status

Accepted

## Context

Users want to install adr-tools with their preferred package manager. For example, Ubuntu users use apt, RedHat users use yum and Mac OS X users use Homebrew.

The developers of adr-tools don't know how, nor have permissions, to use all these packaging and distribution systems. Therefore packaging and distribution must be done by "downstream" parties.

The developers of the tool should not favour any one particular packaging and distribution solution.

## Decision

The adr-tools project will not contain any packaging or distribution scripts and config.

Packaging and distribution will be managed by other projects in separate version control repositories.

## Consequences

The git repo of this project will be simpler.

Eventually, users will not have to use Git to get the software.

We will have to tag releases in the adr-tools repository so that packaging projects know what can be published and how it should be identified.

We will document how users can install the software in this project's README file.

https://github.com/npryce/adr-tools/blob/master/doc/adr/0006-packaging-and-distribution-in-other-version-control-repositories.md

Title

The title should quickly summarize the decision at hand.

Date

In year, month, day format, in order to most easily sort. Also avoids confusion as an international standard.

Status

One of the following:

Proposed
Accepted
Rejected
Superseded - followed by a link to the superseding ADR.

Indicates if the decision is being deliberated, has been accepted or rejected, or superseded by a followup decision, based on changing circumstances.

Context

From there, we have the context under which the decision was made. Users of this tool want to be able to install it in the most natural way on their OS. But currently, and for the foreseeable future, it’s outside the expertise of the team to build and maintain each of these packages. This is a decision that could change, though unlikely. It’s also unlikely that users will stop wanting to install the package via native OS package managers.

This section should include any constraints the organization is operating under, whether technical, financial, time based, or experience based. It should include any other options that are being considered, and the considerations for each option.

Describing the context is the primary future value of the ADR. This is what allows you to look back at the decision clearly and understand the information and constraints that were being operated against. This is also what allows you to know if the circumstances have changed enough to warrant changing the decision.

Decision

It then lists the straightforward decision that limits the scope of responsibility of the repo in a useful way.

The decision will likely be the shortest section, as it doesn’t detail the why, only what decision has been made, and how to act on it. Reasons for the decision belong in the Context and Consequences sections.

Consequences

Finally, it enumerates the consequences of the decision, in the short term and long. This includes new work it creates for the team, as well as benefits. This particular ADR doesn’t detail any potential negative consequences of the decision, because the team doesn’t see any. If there were potential negatives, they would be here as well.

Describing the consequences of the decision allows the future readers to understand how and why a particular judgment call was made, and reflect on if the particular consequences were foreseen with any accuracy, and if not, adjust how they forecast consequences of decisions.

Method

Create a blank new ADR.
Set status to Proposed or Accepted, depending on if this has been decided by the team.
Describe the relevant context surrounding making the decision. This includes business constraints, personnel/skills constraints, environmental reasons, time constraints, cost constraints, or any other information that will be useful in understanding and potentially changing this decision in the future.
Describe the decision that is being made, and will be implemented.
Describe the consequences of this decision. Include the implications for the organization in the short and the long term. How can we best address these to mitigate risks, and maximize benefits. Are there any consequences that haven't been given proper consideration?
Review the ADR yourself.
Publish the ADR for review, actively asking for contradicting opinions and ensuring all relevant context is captured.

Applying the Method

Step 1

ADRs can be created using adr-tools, or simple Markdown templates.

Step 2

Depending on if the decision has already been made, and this serves as documentation for the decision, or if this is a proposal documenting a decision that is being considered.

Step 3

Step 4

Details the decision made against the background of the context.

Step 5

Step 6

Conducting a review of the document yourself is critical to ensuring you’re a good steward of the time of others that you interact with. This ensures you don’t waste their time with issues that you could have seen and addressed in advance.

Step 7

Open up the document for feedback from the team on its content and on the decision, if the decision hasn’t been made. Use it to hold a meeting if necessary to reach a decision, and document it.

Conclusion

Detail the context, the proposed decision, and the consequences. The team can then discuss the proposal and achieve consensus on whether or not to adopt the proposal, or reject it. Either way you keep it around as a record indicating why a given change decision was or was not made, to speed future discussion and work on the same idea.

This is likely not actually the first step in any given cycle, and depending on where you are in the company and its lifecycle may not be something you get to do for a while. Many individual contributors will create these infrequently, depending on the company culture.

ADRs are a powerful tool for understanding why decisions were made and reflect on if and when it’s appropriate to change them, without the fear of changing something without understanding why it exists today.

If you’ve seen success or struggle with implementing ADRs, I’d love to hear about it on Twitter or via email.