ADR = Any Decision Record?

In Part 1 of this story, we went from architectural decisions to more general software design decisions. In this Part 2, we will move on to strategy decisions and then, becoming even more exploratory, any (or arbitrary) decisions.

Strategic Decisions

Let’s investigate cloud strategy as an example domain.

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 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 : “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:

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!

Capture Any Decision?

Now, 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:

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 of 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. More information on this tool is here.

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”.[1] 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.” [2][3]

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.

Markdown Template for “Any Decision Records”

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

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

Wrap Up (Parts 1 and 2)

The take-away messages from this two-part story 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 story[4] inspiring and useful. If so, I’d appreciate a clap.

– Olaf (a.k.a. ZIO) with input from Mirko Stocker and Oliver Kopp

Notes

[1] Thanks to Rolf Dobelli for pointing me at this research via his books.

[2] Citing “The Mindfulness Chronicles” again: “But there were limits to this phenomenon: ‘…because an elephant is after me’ didn’t cut it.”

[3] The complete version of this article originally appeared in the September-October 2010 issue of Harvard Magazine (113:1; 42–45, 71).

[4] This story is available in a single post on my personal blog called “ADR = Any Decision Record? Architecture, Design and Beyond”.

© Olaf Zimmermann, 2021. All rights reserved.