Architectural Decision Record

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, 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, 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.

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 recommended 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 and Marijke Walgraeve for reviewing this post.

Photo by Kaleidico on Unsplash