Well documented: Architecture Decision Records

Heard about Architecture Decision Records? Anyone who moves to a new team quickly faces familiar questions. Why did colleagues solve the problem in this way? Did they not see the consequences? The other approach would have offered many advantages. Or did they see something that I don’t see right now? Architecture Decision Records, or ADRs for short, provide a remedy in such cases.

Origin of the Architecture Decision Records

ADRs originate from the practice of evolutionary architecture. This architecture discipline thinks about the changeability of software. From this comes the realization that software evolves incrementally through adaptations and extensions. Also, decisions are time-dependent. This type of documentation can be traced back to an idea by Michael Nygard in 2011. His employer at the time, ThoughtWorks, placed the idea at several events. Today, ADRs are part of the mainstream.

Knowing and not knowing

Architectural decisions have many influencing factors. Also, our knowledge is a conscious influencing factor. We know what we know. And we also know what we don’t know. That sounds plausible. But our lack of knowledge also influences decisions. We make some decisions based on our instinct without being able to give reasons for them. The lucky mushroom intuitively makes the right decision. But how do we know if we belong to the lucky mushrooms?

Learning from each other

Communication is an essential means of learning knowledge. By talking to each other, we exchange our knowledge. That which we know, we can pass on. And what we don’t know, we can ask. But in the group, we can also uncover our blind spots. What is intuitively correct can be backed up with facts by my counterpart. Or my wrong knowledge can be refuted with arguments. In this way is how we all learn from each other.

Learning with the Architecture Decision Records

The ADR takes up the previously mentioned aspects and consists of several sections:

• The title describes what the issue is.
• The context describes the conditions that led to the decision.
• The decision itself was made based on the information in the context.
• The status in the life cycle of the decision: Proposed, Accepted, Discarded, Deprecated, or Superseded.
• The consequences of the decision, as advantages and disadvantages.

Here, we discuss the different options with colleagues. As a result, there is a transfer of knowledge within the team. Accordingly, discussing the advantages and disadvantages of the possibilities leads to a consensus. At this point, the decision-making process involves everyone in the team. Thereupon, through documentation, this knowledge can be retrieved. Sometimes the team structure changes, and new colleagues join the team. Here, they can use the documentation to understand the decisions made. In this way, they retain knowledge over time. In addition, from time to time, decisions are also critically questioned. Discussing new knowledge or findings keeps the team’s knowledge.

ADR Tooling

Document decisions in simple text form. Tools are not necessary. However, tools can be helpful in processing ADRs. Nat Pryce has published a collection of ADR tools.

Conclusion

Documentation is only good if it provides the proper knowledge. Documentation is not an end in itself. ADRs thrive on team spirit and are helpful if the team supports them. If not all involved are willing, this can also be a reason against documentation. This reason often applies when the team is afraid of making difficult or unpleasant decisions.