Architectural Decision Records are a simple technique that promotes good architectural thinking and better collaboration. They don’t need to be big or complicated to be effective, but they do take some time, and are yet another step between setting goals and delivering value. If you use them in the right circumstances they can be a big help.

What is an Architectural Decision Record?

An Architectural Decision Record (often abbreviated ADR) is just as the name implies: a document that describes an architectural decision. It can include various details, but should at a minimum describe the problem being solved and the solution that was chosen. It can be a simple text document with a page or two of text, or it can be longer with specific sections that are important to the team.

Why use Architectural Decision Records?

The most obvious benefit of architectural decision records is that they record your important technical decisions. Years later, if you’re considering replacing Framework X, you can see the original analysis that went into its selection. There may have been good reasons your new candidate wasn’t chosen. Or more likely, the decision may have been based on assumptions that are now known to be invalid.

My favourite reason for using Architectural Decision Records is that they are an easy way to encourage good architectural habits. For example, forcing a developer to write down the problem they are trying to solve makes it harder to add technologies with no purpose (yes, this happens). Asking for alternatives considered makes sure that alternatives were actually considered. Even considering if an ADR is necessary is a valuable exercise.

The process of writing and reviewing ADRs also makes technical decisions more visible, and accessible to more of the team. With these simple guardrails in place, you can hand a decision off to an intermediate developer and know that your most senior developers will still be involved. Distributing work like this helps prevent bottlenecks, but it also gives everyone a chance to grow their skills.

Having a formal decision-making process is especially helpful for big teams where decisions can impact a lot of people. Or if a team has a partially involved architect. When I was an architect with responsibilities for multiple teams, I found this process to be an excellent way to stay in the loop, and a great entry point to get involved when needed.

When should I use an Architectural Decision Record process?

This is really two different-but-not-so-different questions: when should a team have an ADR process, and what kind of changes should require an ADR process? The answer to both is effectively the same thing: when is a decision architecturally significant?

The way I answer this question is to ask what the impact would be if the decision is wrong. If there is a low risk of serious consequences and I can easily change to a different solution, then I make a good-enough choice and move on.

Here is an incomplete list of reasons why a decision might be architecturally significant:

  • A lot of code would need to be rewritten if the decision gets changed. For example, when selecting a:
    • programming language
    • base framework
    • automated test framework
  • Mistakes could have serious impacts. For example, if the project/change has anything to do with:
    • the privacy of sensitive data
    • security
    • financial transactions
    • life-critical systems
    • civic infrastructure
  • The software is used by many different teams, and a change could impact many of them. For example: something exposed in the api of an open-source library or shared module used by multiple teams
  • The software could be used and maintained for many years or have a lot of different people working on it
  • The software is difficult to change if there is a mistake. For example: firmware

If any of the above are true for your project generally, then implementing a formal ADR process could be helpful.

When you have an ADR process, you should also provide some guidance about when it needs to be used. For the same reasons, it makes sense to base it on the potential impact of a wrong decision. You can use an arbitrary replacement cost for your definition (for example: “more than a week of effort to replace”), or list potential impacts like privacy or security risks.

Even without a formal ADR process, individual contributors can also benefit from using one of these templates. Filling out a good template makes sure you truly understand your problem and that you don’t skip any important steps. This is helpful even without soliciting feedback. I use this technique myself sometimes. This is also effectively what my Architectural Report template is.

Can I introduce an Architectural Decision Record process to an existing project?

Yes, but it’s harder for the team to appreciate the value of it.

You get all the benefits of standardizing the decision-making process, but it’s hard to realize the value of documentation without a significant majority of your important decisions documented. Retroactively documenting decisions isn’t very practical either: without tremendous notes or exceptional memory, the results can easily lack sufficient value.

If you have a strong reason to improve the quality of future decisions, and the team believes in it, then you have a shot at adding an ADR process to an existing project. I wouldn’t recommend it otherwise.

What Architectural Decision Record template should I use?

You can find several decent templates with a quick internet search. Joel Parker Henderson has helpfully posted a list of Architecture Decision Record templates and some other helpful resources in GitHub, which I’ve used in the past.

My favourite template is the Decision record template by Michael Nygard. I appreciate its simplicity as a starting point, and it’s trivial to add other sections as you need them.

The best template will depend ultimately on the benefits you want to get from your ADR process. For example, if you’re building life-critical systems you might include a section for safety testing measures to make sure they are considered with every decision. If your organization is concerned with copy-left licensing, you can include a section for any new dependencies and their licences.

Where should I store Architectural Decision Records?

The best place to store these documents is the place your team will look for them. If you have a wiki where all your technical documentation goes, that is a good choice. Some people like to put these records into source control, and that’s a good choice too. Whatever location you choose, make sure it has good search facilities and some kind of change history. A mechanism for giving feedback in the document itself is nice as well.

One advantage to source control is that you can use your familiar code review tools and processes to manage them. One drawback to source control is that it encourages simple text formats, and that makes it harder to include diagrams or other rich content.

If you do put your ADRs into source control, think about which repository they belong in. Some people like to keep them in the same repository as the code they relate to, but this won’t work if your project spans multiple repositories. If you use branches heavily, it may be confusing to see the documents in different while working. When in doubt, create a new repository for your technical documentation.

Another detail to consider is the scope of the decisions being made. If your team maintains multiple pieces of software you might have different (and conflicting) decisions for each of them. Make sure it’s obvious what your documents apply to.

Maintaining Architectural Decision Records

Decision records can get stale with time. If you do start using them, remember to also occasionally go through and clean them up.

To help with this, many teams use an append-only approach. If a decision gets replaced, a new document will be created, and the old decision will get a note inserted marking it as deprecated. Decision records can be numbered to make cross-referencing them easier.

Summary

Architectural Decision Records can improve your architectural thinking without much effort, and they have the added benefit of leaving useful documentation behind. If you add them early in a project, they can improve the quality of the decisions your team makes.