What are Architectural Decision Records (ADR)?

One of the most painful parts of starting with a new team is to learn all of the nuanced patterns and practices you must adhere to. Often these nuances are not documented and to make matters worse, the common response given for why is, "that is just how we do it here". The tribal knowledge runs so deep it starts to look like cargo cult culture and in some cases it is just that.

One of the best ways to ensure new team members get up to speed quickly without the pain is through Architectural Decision Records, commonly referred to as an ADR. These documents are intended to be quick and concise records of the decisions that were made along with the context and consequences of the decision. These documents are usually stored along side your code in a source control repository where they are easy to find and changes are traceable.

Two key attributes of ADRs are quick and concise. Let's be honest, few of us like spending time writing and reading documentation. To compound that, stakeholders are generally not going to give us more time to write and read documentation. As you will see later in this article, there is a treasure trove of great templates and examples out there that are quick and concise.

Beyond the challenges of onboarding new members of your team, ADRs can also help you decide when to reconsider an important decision that was made in the past. We live in a rapidly evolving domain and sometimes the reasons we made a decision in the past are no longer relevant. If we don't have a record documenting the reasons, then it is difficult to have a constructive discussion as to why the decision might need to be reconsidered. Think of it like being kind to your future self.

ADR Template

There are a number of templates for ADRs, but my favorite is one that is attributed to Michael Nygard.

• Title
• Status
  • What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
• Context
  • What is the issue that we're seeing that is motivating this decision or change?
• Decision
  • What is the change that we're proposing and/or doing?
• Consequences
  • What becomes easier or more difficult to do because of this change?

As you can see it is quick and concise. I did a quick scan of Arachne Framework's repo of ADR and found that the average length was about 100 lines, with many being in the 50 to 100 lines. The largest one I found was 280 lines. These are not long documents and are easy to consume and in most cases probably did not take that long to write.

When defining the ADR template for your organization, remember that this is function over form. The more you add to your template, the less likely the documentation will be maintained or consumed. Current and complete documentation that might not be pretty to look at, is much more valuable than stale and sparse documentation.

When to create an ADR?

Create an ADR at the point where the architectural question is raised. This will give your team a place holder to collaborate on the question and document the discussion as it is ongoing.

It is perfectly acceptable to have an ADR that is pending or even undecided. Building software is an empirical process and sometimes just knowing what the questions are can be valuable. I can't count the number of times I've run into a problem and had the notion that an issue was discussed in the past with a team, but everyone is foggy on what the details were. Having an ADR to reference would have been valuable in that case, even if it said we decided not to pick a solution at that time.

Best tools for creating an ADR

In my opinion the best tools for creating an ADR are the ones we already have. A Git repo and Markdown files are my new favorite documentation tools. Markdown is so simple to work with and it can be managed in a Git repo just like you manage code. Feature branches and pull requests work well for allowing everyone on the team to suggest changes, while at the same time including some controls on what is approved and what is proposed.

In addition, most of the Git repos I've worked with recently have a Markdown viewer and editor built into the web interface. This includes GitHub, GitLab and Azure DevOps. You can edit and view documentation right in the repo or use an external Markdown Editor.

I've tried a number of different Markdown editing tools and I have found VS Code is my favorite as I already have it installed and it integrates nicely with Git repos. Add a spelling extension to VS Code and you have some real magic there.

Who creates an ADR?

Collaborate with your team is the best answer for who creates an ADR. It is always easier to get buy in from the team if they have some ownership in the end product. Besides, this is a situation where perspectives from multiple participants will result in a better thought out decision.

That said, there should be an architect or principal software engineer that is responsible for making sure the ADR is documented properly, coordinates the discussion and approves the pull requests. If everyone on the team is responsible, then no one is responsible and ADRs will be another great idea that doesn't get follow through.

In Conclusion

As long as they are quick and concise, Architectural Decision Records are a powerful tool for onboarding new team members and helping your current team members remember why a decision was made. There is no greater satisfaction than getting a high-five from your future self.

Resources

• GitHub Repo with examples and more information
• A Simple but Powerful Tool to Record Your Architectural Decisions
• When Should I Write an Architecture Decision Record