ADR = Any Decision Record? Architecture, Design and Beyond

If architectural decision records are so useful to capture software design rationale, why not extend their scope: Can they log organizational and managerial decisions as well? How about everyday decisions?

Architectural Significance and Decision Making Criteria

In “Architectural Decisions — The Making Of”, I motivated why Architectural Decision Records (ADRs) are such an important software architecture artifact and featured a few templates, including Y-Statements (my own creation). Let’s take a step back and carve out what makes a decision architectural, and then discuss whether the ADR templates are general enough to capture other types of decisions as well.

Which decisions should architects make? Martin Fowler described an Architectural Decision (AD) as “a decision that you wish you could get right early” in an IEEE Software article. Grady Booch elaborated “a design decision that is costly to change” in his SATURN 2016 keynote. My three-part definition from 2009 is in line with those of the luminaries:

1. Architectural decisions directly or indirectly determine the non-functional characteristics (or qualities) of a system (think -ilities or consult this post for examples).
2. Each decision describes a concrete, architecturally significant design issue (problem) for which several potential solution options exist and provides rationale for the decision outcome (the selection of the chosen solution option, that is), for instance by arguing whether and how the desired quality attributes will be achieved.
3. Architectural decisions concern a software system as a whole, or one or more of the core components of such system (whatever the “core” might be).

Examples are the selection of programming languages and tools, of architectural patterns, of integration technologies and of middleware assets. The post “Architectural Significance Criteria and Some Core Decisions Required” identifies some more core decisions.¹

What makes an issue architecturally significant? By intent, all three AD definitions above are somewhat fuzzy; hence, I developed an architectural significance test. This test (elaborated upon in the previous post too) uses seven criteria to assess significance quickly:

1. Impact on business value and risk?
2. Key stakeholder concern?
3. Unusual quality-of-service requirement (at least one order of magnitude more advanced than previous ones)?
4. About external dependencies that are uncontrollable, unpredictable or unreliable?
5. Cross-cutting, system-wide impact?
6. First-of-a-kind character (novelty for team)?
7. Caused bad experience and trouble in the past?

How to make such decisions? Context matters when it comes to experience sharing; therefore simplistic best practices rules and design-by-authority are bound to fail in the real world. This makes architectural decision knowledge precious, but also difficult to share.

Most decision making is a team sport, researched under keywords such as “group decision making”. In “A Definition of Done for Architectural Decision Making”, I discuss the process somewhat and propose five criteria to assess whether a single AD can be considered done:

Decisions should be prepared, made and captured at the Most Responsible Moment (MRM).² And only the key ones should be documented thoroughly. So far so good, but:

Where to draw the line between architecture and design (and other) decisions, if any?

Enter Design Decision Capturing

I follow Grady Booch in that “all architecture is design but not all design is architecture” (source). The seven criteria in the architectural significance test express this is-a relation. So let’s try to find the boundary.

Sample decision with high architectural significance. The JabRef project concerns the domain of literature management; querying digital libraries for bibliographic information is an important feature set. Hence, its design decision on query syntax is a good example of one that meets the three-part definition of ADs from above:

This decision addresses the usability quality in a core component of the system. It calls out options and criteria regarding a design issue. More precisely, it certainly meets at least a few of the seven test criteria: The product owner will be unhappy if users walk away due to a crude query syntax; chances are that the open source contributors do not have to design query engines every week; a dependency to Apache Lucene is mentioned in the ADR.

Example of a borderline decision. Some design issues do not pass the significance test as easily as the previous example. Are such non-architectural design decisions worth capturing too? Do ADR templates such as this one still work?

How about the following decision (also from the JabRef project)?

We could argue that a cumbersome layout of the change log degrades usability and maintainability, so it is architectural (but to a lesser extend than the query syntax issue).

A decision that does not pass the architectural significance test. The next example comes from the Eclipse Winery project:

Are file naming conventions architecturally significant? Hopefully not (but who knows?).³ Either way, the decision record above still reads well and captures valuable information. So we can conclude:

Capturing key design decisions, even if not architecturally significant, is useful and possible.

Can we take another step now, from design to information technology in general (or even further)? Let’s take cloud strategy as an example.

Strategic Decisions

Gregor Hohpe, of “Enterprise Integration Patterns” fame and now providing IT strategy and cloud transformation advice, emphasizes the importance of decisions and decision making for architects, but also adopts business-level decision option theory. Decisions stay with him as he takes “The Software Architect Elevator” (from engine room to penthouse):

• ADs and their rationale make a system fit for purpose, see here and here.
• The options metaphor from the finance domain is discussed in “Architecture: Selling Options”. An option is a way to defer a decision, which has cost and value attached.
• Gregor’s book “Cloud Strategy — A Decision-Based Approach to Successful Cloud Migration” has our topic in the subtitle. Two examples of decisions required are deciding about multi-cloud options and how to avoid or contain (vendor) lock-in. Searching for “decision” in the book yields 168 hits because “a sound strategy is defined by a series of meaningful decisions”.

Having arrived on the strategy level, we can generalize even further. Management decisions, for instance about (re-)organizations, can be captured in the same way. Here’s how Gregor might have decided to include the FROSST principles from a colleague:

1
2
3
4
5
6
In the context of the Cloud Strategy book,
facing the need for a set of principles that are meaningful, intuitive, and easy to remember,
I decided for Frugal, Relocatable, Observable, Seamlessly updatable, internally Secured, failure Tolerant (FROSST)
and against Heroku's Twelve-Factor App or IDEAL (from the book "Cloud Computing Patterns")
to achieve that readers can remember the key characteristics of applications and that I avoid buzzwords and jargon,
accepting that I have to write more and that readers have to learn a new acronym.

Note that I made this Y-Statement up during a discussion on LinkedIn about a year ago, paraphrasing from pages 193 and 194 in “Cloud Strategy”.

We take away:

Engineers make many decisions, strategists too (and everybody else). They should capture their decisions to preserve the decision drives and decision rationale. Room for (A)DRs!

Any Decision?

How about everyday life: What to have for lunch? Which job offer to accept? And anything in between? Here is a Y-Statement for a decision from the personal mobility domain:⁴

1
2
3
4
5
6
7
In the context of individual transportation in and between cities 
  facing the desire to commute cost-efficiently and environment-friendly 
I decided for a hybrid car and neglected those with combustion engines only 
  to achieve a reduction of my personal CO2 footprint
accepting that I have to pay a higher price
  and take some risk regarding charging (reach? cost?) 
    and future technology evolution (battery life and recycling?).

The last two parts (lines 3 to 7 in the ADR) can — and should — provoke a discussion about pros and cons of the options. The decision capture can even unveil missed options (and criteria):

• Does it makes sense to defer the decision? Should I stick to my old car for another year or two?
• Should I decide twice, short-term and long-term, and buy a fully electric car once technology has matured even further?
• How about not buying a new vehicle, but joining a car sharing initiative or use public transportation?

All complex problems require conscious decisions, which can and should be captured in a lean and recognizable/reproducible way. Give it a try!

If you justify, you’ll make better decisions and increase chances of agreement (see below).

Related Work

Actually, decision making and capturing has been proposed in other communities before research on software architectural knowledge management and ADs peaked (possible search keyword: “design rationale”).

HCI Community. The Human-Computer Interaction (HCI) community contributed Questions, Options, Criteria (QOC) diagrams in the 1990s. A frequently cited paper that features QOCing is “Questions, options, and criteria: elements of design space analysis” by Allan MacLean, Richard M. Young, Victoria Bellotti and Thomas P. Moran.

AD Mentor, an extension to the UML (and other) modeling tool Enterprise Architect, supports QOC diagrams.

Decision Making Podcast Episodes. The Knowledge Project at Farnam Street Media has a topic area Decision Making.

SDM. Structured Decision Making website and book address the domain of environmental management choices. But have a look at its steps and tools!

Planning and Sensemaking. Decision capturing — and upfront question, option, criteria modeling — is particularly useful when facing complex and wicked problems (i.e., those you can only partially solve, and in multiple ways). The technique of dialogue mapping, for instance, has been used in tackling wicked problems in organizations using a collaborative approach.

Workshop technique and notation are featured in the book “Dialogue Mapping: Building Shared Understanding of Wicked Problems”. And supporting (g)IBIS tools have been proposed.

Social Psychology. You can even provide trivial decision rationale in your ADRs and still increase chances of getting them accepted.

A 1978 paper on “The mindlessness of ostensibly thoughtful action” by Ellen Langer, Arthur Blank and Benzion Chanowitz reports on the now famous “Xerox experiment”.⁵ Quoting from “The Mindfulness Chronicles: On ‘the psychology of possibility’” by Cara Feinberg,⁶ “the researchers approached people using copying machines and asked if they could cut in line. The reasons given, if any, ranged from the sensible to the senseless: for instance, ‘May I use the Xerox machine because I’m in a rush?’ versus ‘May I use the Xerox machine because I want to make copies?’ They found that subjects overall were more amenable when given a reason, but were equally compliant whether the reason was real or ridiculous. Their behavior, she showed, was mindless: people responded more to the familiar framework of a request than to the content of the actual question”.⁷

To summarize:

Almost any justification is better than none (depending on your goals).

This effect is also known as “just because”. Be aware of it as a decision maker and capturer!

If template usage turns into cargo cult, not much is gained. Provide decent rationale.

New: Markdown Template for “Any Decision Records”

The broadened scope of ADRs proposed in this post has the following consequence:

📢 The MADR project on GitHub repurposes and generalizes the acronym “MADR” from “Markdown Architectural Decision Record” to “Markdown (for) Any Decision Record” in Version 3.0.0 of the MADR template and tools.

Wrap Up

The take-away messages from this post are:

• Architecture Decision Records (ADRs) have found their way into the software engineering mainstream; creating them pays off in the medium to long run.
• All architecture is design, but not vice versa. Many design decisions that do not qualify as architecturally significant are still worth capturing.
• Not all decisions are worth capturing; triages are required. Checklists and criteria can help with that and with ending the making of a decision (to move on to the next issue).
• Autonomous teams and technical leaders make many managerial and organizations decisions; ADR formats such as MADR and Y-statements can capture such decisions as well (including strategy decisions). Almost any justification increases chances of getting a decision accepted.
• Consequently, MADR will stand for Markdown (template and tools for) Any Decision Records from now on.

I hope you found this post useful. Let me know.

– Olaf (a.k.a. ZIO) (with feedback and input from Mirko Stocker and Oliver Kopp on MADR, JabRef and Winery)

Medium edition: This post also comes as a two-part Medium story (Part 1, Part 2).

Deeper coverage: Mirko Stocker and Olaf Zimmermann have an ebook called “Design Practice Reference” under construction, which covers architectural decision making among other software engineering practices.

Notes