Architecture Decision Records help you, your team, and future teams

Over and over again the same story plays out. A new developer joins the team, takes one look at a repo, and asks the inevitable question: “WHY?!”

Most of the time there is no answer – the original creators are long gone, or it was so long ago no one remembers, or the decision was dictated and no one thought to (or was comfortable enough to) question it at the time. With no satisfactory answer available, the next inevitable thing happens: “Well, should we revisit this or fix it?” Queue the long arguments about effort, cost, time, and priorities!

We’re here to tell you that there’s another way. A way that can foster discussion, record the whys, and let Future You and Future New Person know exactly what the team was thinking when the decision was made. Architecture Decision Records (henceforth referred to as ADRs to save us some typing) are here to save the day!

The basics of Architecture Decision Records

A favourite place to send people to when introducing the subject of architecture decision records is Joel Parker Henderson’s ADR repo. He includes a list of starting templates that can help with initial understanding, but you’ll want to customize and iterate on your team’s template as you get used to the format.

That said, here’s an example—based on the MADR template—we’ll walk through:

# Improve morale with rainbow emojis 🌈🌈
​
- Status: accepted
- Deciders: Kyle Adams
- Date: 2022-03-03
​
# Context and problem statement
​
As Yoda, speaking in haiku form, would say:

Docs lead to boredom
Boredom leads to dev sadness
Sad devs to exit

How do we improve developer morale?
​
# Considered options
​
- Bouncy houses
- Free ice cream for life
- Rainbow emojis 🌈🌈
​
# Decision outcome
​
We chose the option: "Rainbow emojis 🌈🌈", because:
​
- Emojis are cheap
- Rainbows are the exact opposite of gloomy
- Documentation with emojis is proven to be 100% more engaging

‍The first section is relatively self-explanatory: you want a clear title, the status of the decision (ie draft, review, accepted), the people who own the decision (although the entire team is ideally part of the discussion), and the date the decision was made. Next, let’s review the other sections and why they are critical components to architecture decision records.

Context and problem statement

The context and problem statement is probably the most important part of the entire document. This is where you explain what the problem is and why it’s a problem. As developers, we should always strive to know why we’re taking any action. After all, if we don’t know why we’re doing something, why would we do it?

It’s possible you may be trying to fill in ADRs for older decisions to backfill this kind of documentation. Generally, we don’t recommend going too far back, but if you feel you have to you’ll likely need to do some code and task spelunking to fill this section out.

Worst case scenario, you might be stuck putting in a “best guess” on the original problem statement. That’s okay, but if that’s the case you should add a small disclaimer saying that the original problem and context has been lost to time.

For new decisions, try to be as clear as possible. This is one place it’s better to have too many details than not enough.

Try to put yourself in the mind of a brand-new employee or product owner who is trying to develop an understanding while onboarding.

Don’t bother being overly technical – this occasionally leads to dictating how the problem should be solved, and we want to avoid that. Instead, focus on giving the decision real meaning for every member of the team.

Options to build out ADRs

There are a couple of options around how to build out ADRs that are likely to affect these sections.

For example, if you’re having a meeting to discuss the problem, the Considered Options section might be a rather large collection of notes from the discussion. If you’re creating ADRs in a repo and having asynchronous comments feeding the decision, this section is more likely to be a very small summary of the main options, since anyone can go to the original Peer Review and see the full discussion.

For Decision Outcome, again there are options. Some teams like to split this out into three sections, detailing the final decision, positive impacts, and consequences separately. Other teams like to use this section to link to any related Peer Reviews or task items that were created as a result of the discussion. It’s really up to what’s most useful for the team and for new members coming in.

Where should Architecture Decision Records live?

As with all process items, where these records live is really up to the team. That said, there are a few things that should be considered:

•  Can anyone find and search the records easily?
•  How close to the impacted item can we place them (e.g. in the same repo in a /decisions/ folder)?
•  Do we need different places based on the type of decision (e.g. a shared drive if the decision impacts multiple teams or repos)?
•  Is it easy to change and comment on the documents once created?
•  Can we add pictures and diagrams easily?

Generally, you’ll see repo-specific decisions in the repo they relate to and team-wide decisions wherever other team-wide documentation lives. There are also a bunch of tools that allow you to organize and deploy ADRs in various ways, often ending in them being published to GitHub Pages or something similar.

Which decisions do we write these for?

This will change depending on where your team is in their lifecycle and where your products are in theirs. If it’s a brand-new team, you can use ADRs to ease the storming stage as a guide to work through decisions around processes, preferences, tools, codes of conduct, etcetera! There are always a ton of decisions and discussions when an engineering team is new, and architecture decision records can help the team codify all those decisions.

If you’re starting a new repo or product, you can use ADRs when picking everything from data storage to language and frameworks to linters! Capturing these decisions and the reasons behind them is a huge win for anyone who ever joins your team in the future, and may even be able to inform your manager’s hiring decisions.

For example, in an interview, you could give a potential candidate the Context and Problem Statement for something you already have an ADR for and see if they come to the same ideas – or think of something your team missed entirely!

For long-running products, ADRs can come in handy when talking through major refactors, tool additions, or major new features the business wants to add. You’ll want to be more nuanced in what you use ADRs for here. The goal is to make decisions easier for the team to agree on and understand, not bury the team under documentation and process.

In all of this advice, the key thing to remember is the first tenet of Agile: People before Process.