Facilitating Software Architecture

Chapter 6. Architectural Decision Records

Although the architecture advice process will transform your organization’s decision processes, I always combine it with at least one further element: architectural decision records (ADRs). They are the best way I know to mitigate the three confidence deficiencies that I discussed in the previous chapter: in your and others’ deciding skills, in the advice seeking and offering, and in knowing everything that is happening.

I consider ADRs the essential add-on to an advice process base model, supporting and enhancing all its key aspects. ADRs help everyone make better decisions, and advice seeking and sharing happen in the open. Best of all, ADRs maintain a transparent, accessible history of all decisions for everyone, including the supporting advice. That helps build and maintain trust and is a great resource for learning.

In this chapter, I’ll use two examples to illustrate how writing ADRs supports your decision process. I’ll show how the structure of ADRs can be used to understand the context of decisions and as a means to think in a structured way about your various options and their consequences. I’ll also demonstrate how ADRs provide invaluable support to the smooth running of the advice process, regardless of how you choose to manage and maintain them throughout their productive and valuable lifecycle.

Let’s introduce ADRs, starting with where they sit within the advice process.

Introducing Architectural Decision Records

ADRs support ...