Architectural Decision Record
Tags: development, architecture
Published: 2021-04-09 06:28:24

---
title: Architectural Decision Record
published: true
date: 2021-04-08 06:53:59 UTC
tags: development,architecture
canonical_url: https://www.timsommer.be/architectural-decision-record/
---

 ![Architectural Decision Record](https://www.timsommer.be/content/images/2021/04/kaleidico-26MJGnCM0Wc-unsplash.jpg)

I firmly believe there is no such thing as a "bad" or a "good" architecture. It either fits the business needs from a technical perspective, or it doesn't. A technical design is always the result of a series of "choices" and "decisions" throughout the lifetime of that design. But it's not good or bad, it's a matter of how [_fit_ the design is](https://www.timsommer.be/using-fitness-functions-to-create-evolving-architectures/), given the _current and historical constraints and requirements_.

It's critical that you hold a good "record" or "log" of those design decisions. Because that's the reason why any design is at a certain state, at any given point in time. This post is meant to aid developers and architects into creating such "decision logs". And for this, we will use Architectural Decision Records (or ADR's).

## The art of decision making

Having to make decisions on a regular basis can create a great deal of uncertainty and anxiety. Especially if that decision has an impact on the evolvability of your design. _Did I think this decision over long enough? Did I take enough data into consideration?_ But in the end, you'll find that you never could take enough data into consideration. _The data for any given situation is infinite_.

And as such, worriers are people who think of all the variables beyond their control, and what might happen, and as a result are afraid to make the wrong decision.

To be clear, I'm not implying that you shouldn't think about your decisions. But you _should never be afraid to make one_. Even if every decision you make throughout the path of your evolving design is wrong, as long as your design is evolving, you're on the correct path. And as long as you record your decision process, you open new doors down the road, to correct the incorrect.

## ADR's

Your technical documentation should have different "types". A high level (system-) design, an application design, infrastructure details, etc.   
ADR's are a bit a-typical, but they should **not (!)** be regarded as a replacement for other types of technical documentation!

The Architectural Decision Record (as the name implies) is a log of decisions made by a team while they evolve the design of their application. It can be documented in many ways, with all sorts of templates. It should, however, always include the following information:

- **ADR Lead**   
The person(s) taking charge of the ADR. 
- **Status**  
The status of the ADR in its lifecycle. Examples could be "Draft", "In Review", "Decision Presented", "Implementation started", "Implemented", "Closed".
- **Context**  
The context of the problem for which the ADR will provide a solution. What are you trying to decide? What problem are you trying to solve? 
- **Solution(s)**  
Once you've defined the problem you should think about different solutions. Always try to define more than one! This motivates out-of-the-box thinking, weighing up benefits versus drawbacks, implementation costs, etc.
- **Risk analysis**  
Some sort of risk calculation. What degree of risk does the current problem introduce. How will the different solutions work towards mitigation of those risks?
- **Requirements**  
What requirements must be met? You can use the [MoSCoW method](https://en.wikipedia.org/wiki/MoSCoW_method), or any other system you like. Make sure your requirements are crystal clear! 
- **Estimations**  
How much will each solution cost? This will impact the final decision, so this is an important part of the ADR. The most elegant solution will not always be the right solution. It should be realistic, and for this, cost/benefit evaluation is critical. 
- **The decision!**   
Eventually, you'll have to make a decision. Which in turn will be presented to project management. You should be able to explain what you want to do, why you need to do it and how much time you will need.   
Notice that all previous steps are formal checkpoints to allow you to make the best possible choice and to take into account as much data as possible.

So an ADR, once integrated in your technical workflow, allows you to _document_ _informed decisions in a formal way_.  A _design record is created for future reference_, and can be used to _present your decisions to management_ in a formal and conclusive way.

A solution summary will look something like the picture below.

![Architectural Decision Record](https://www.timsommer.be/content/images/2021/04/2021-04-06-11_38_23-Edit---ADR.004---SonarQube-Metrics---QFRAME-Algemeen---Confluence---Mozilla-Fire-1.png)

## Decision process

So, I've explained the what, who and why of ADR's. Let's take a look at the how. When documenting ADR's, keep the following in mind:

- The main goal is to document the decision process.
- An ADR should always have one person in the "lead", someone who is _responsible for researching the problem_. Choosing a r_ecommended solution is a team responsibility_. Giving a _green light for that solution is a management responsibility_.  
- The whole team should be involved in the finalization of the ADR. Everyone should understand the research and the decision process. The conclusion should be _unanimous_. **An ADR is a living document**! Everyone has a say, everyone can view, and everyone has a vote. The more people involved, the better the decision will be. 
- Allow all members of your team to take lead on ADR's. This allows them to become more experienced, to learn to think outside the box and gain more confidence in the decision making process. 

## Conclusion

Architectural Decision Records are a powerful tool for documenting the design decision making process.   
Does that mean that you will now automatically make all the right decisions with these ADR's? Nope. But it will provide insights as to why certain choices were made. If the decision turns out wrong, the most valuable part is _getting a grasp on why_ it was wrong. Who made the call, did he/she have the right information, did anyone else see the problem in a different way? This information is extremely valuable for evolving your design in the way you want, and to gain more experience in the process.

Big thanks to [Karin Wauters](https://www.linkedin.com/in/karinwauters/) and [Marijke Walgraeve](https://www.linkedin.com/in/marijke-walgraeve-7320846b/) for reviewing this post.

Photo by [Kaleidico](https://unsplash.com/@kaleidico?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)