Architectural Decisions — The Making Of

Architectural Decisions (ADs) have been answering “why” questions about design options since the inception of software architecture in the 1990s. Ways to capture them should be part of each architect’s toolbox. Less is more — only the key ADs justify the effort, and only crisp and sound justifications will convince the reader. Let’s see how to get there.

Motivation

Let’s start with an example, made up from a true story:¹

An agile software development team welcomes a new member, let’s assume an external consultant. The newbie starts challenging the current design instantly and provocatively:

• “Why did you decide for server-side rendering, a Single Page Application (SPA) executing JavaScript in the browser is way more responsive and efficient?”
• “Shouldn’t the client and the server use JSON rather than XML to exchange data?”
• “How could you bet the future of the product on a dated technology such as JSF?”

These issues were discussed multiple times, but nobody remembers which options were considered and which criteria drove the final section. Actually, some of the opinion leaders have left the project or the company since then. The ones that stayed do not remember the line of thinking and detailed arguments at the time — so much has happened since then.

Does this sound familiar? If the same questions are reconsidered time and time again, progressive iterations turn into “we have been here before” circles. A decision log can answer the questions and “silence” the newbie (who probably had good intentions).

A Bit of History

Architectural Decisions (ADs) have always been important. Some teams make them a bit more explicit(ly) than others — but we all want to decide at the most responsible moment, and even the most agile teams capture the essential ones somehow.

Method engineers and practice leaders therefore have had a lot to say about ADs for quite some time, and still have. We can identify three phases of awareness and adoption:

1. Rise/differentiator phase. In the 1990s, ADs received less attention than notations such as UML or ADLs, but they were definitely there already:
   • The term “rationale” was introduced as one of three components of any software architecture in a research paper in 1992.²
   • Software vendors and professional services firms established templates for their staff, but usually did not publish them (this was before blogging and open sourcing became popular). For instance, the work product ARC-100 in the IBM Global Services Method was called — surprise, surprise — Architectural Decisions.³
   • The commercial Rational Unified Process (RUP)⁴ also included a decision guideline, which has become a bit hard to find online (for instance, in OpenUP).
2. Trend/boom phase. In the 2000s, Architectural Knowledge Management (AKM) and ADs became a hot topic in software architecture research, and senior architects in industry began to share their AKM practices with the public:
   • A Groningen workshop in 2004 kicked an intensive period of research off. For instance, A. Jansen set the scene and P. Kruchten donated a taxonomy. R. Capilla, U. van Heesch and others suggested to let decisions form a dedicated viewpoint.
   • J. Tyree and A. Akerman from CapitalOne took inspiration from the IBM e-business Reference Architecture (that came with pre-filled AD records) and motivated why ADs matter in an article in IEEE Software that also presented a rich template.
   • In my PhD thesis, I investigated whether AD issues recur when similar designs are used on multiple projects, and whether decision trees can be mined from the gained experiences. I suggested a method to identify the need for ADs and the available options in requirements and style definitions systematically. Service-Oriented Architecture (SOA) served as an exemplary architectural style that I tried my methods and models on. One such decision model became a company-internal knowledge asset; all concepts and many examples of AD issues, options, and criteria appear in my research papers from that time.
   • The ISO/IEC/IEEE 42010 standard was released. Arguably one of the most readable standards of all times, it recommends to capture decision rationale and gives scoping and filtering advice (and clarifies many other concepts).
   • Academic conferences such as WICSA and ECSA and scientific journals presented numerous research results, some of which found their way into practice or inspired others. For instance, the connection between ADs and patterns was investigated by a number of researchers (ArchPaD was my take, as joint work with Uwe Zdun). The Springer book “Software Architecture Knowledge Management” compiled chapters from many AKM/AD researchers around the world; I was lucky enough to be able to contribute a case study on SOA infrastructure decision reuse. “A comparative study of architecture knowledge management tools” by Antony Tang et al has the full tool story (as of 2010).
3. Commodity/must have phase (since 2010). ADs have now made it into the industry project mainstream:
   • M. Nygard received a lot of attention with his Architecture Decisions Records (ADR) blog post. The topic regularly appears at software architecture conferences such as SATURN.
   • The architecture documentation template arc42 dedicates Section 9 to ADs and gives nine related tips.
   • Tools were released. Open source ones that I contributed to include Markdown Architectural Decision Records (MADR), initiated by Oliver Kopp (who needed a template for his master student projects), and AD Mentor, an add-in for Enterprise Architect (joint work with Heiko Koziolek and Thomas Goldschmidt from ABB).

So the ARC-100 work product from the 1990s was right: “there are no reasons not to have this work product.” ADs are here to stay. There even is a Wikipedia page on ADs now.

We know about importance and history of AD making now — but we still aren’t sure yet which ones to focus on and how to capture them. The latter topic (how to capture) is next up in this post; the former (which ones to capture) has to wait for another one — please have a look at Hint 9-1: “Document only architecturally relevant decisions” in arc42 or this workshop paper if you cannot wait (the “meta issues” in the paper will work for any style).

Y-Statements and other Templates

As a consulting IT architect at IBM, I followed the ARC 100 template, usually trimmed down a bit (following my first law of method adoption: “if in doubt, leave it out”). On the SOAD PhD project, I proposed a richer meta model, optimized for decision reuse (i.e., decisions required, not decisions made). However, I had to learn not to overdo it: the maintenance effort of filled out, full-fledged decision records (that are shared between projects) became rather high.

My next two projects had senior managers and tech leads as sponsors, who did not want to spend too much of their precious time on reviewing lengthy text documents. To quote one of the catchers of my work: “can you fit each decision on one presentation slide?”. Giving people what they want is not necessarily a bad idea, especially if these people sponsor your project. So I rethought my approach to AD capturing and sharing and tried to focus on the bare essentials of a decision.

The result: (WH)Y-statements, presented at SATURN 2012, used on a large C-level enterprise transformation and IoT cloud project and published in an IEEE Software/InfoQ article:

1
2
3
4
5
6
In the context of the Web shop service, 
facing the need to keep user session data consistent and current across shop instances, 
we decided for the Database Session State Pattern 
and neglected Client Session State or Server Session State
to achieve cloud elasticity, 
accepting that a session database needs to be designed, implemented, and replicated.

Each template element appears on one line in the above example:⁵

1. context: functional requirement (user story or use case) or an architecture component,
2. facing: non-functional requirement, for instance a desired quality,
3. we decided for: decision outcome, arguably the most important part,
4. and neglected: alternatives not chosen (not to be forgotten!),
5. to achieve: benefits, the full or partial satisfaction of the requirement,
6. accepting that: drawbacks, impact on other properties/context and effort/cost.

This template is is much leaner than my previous attempts. Its six sections form one (rather long) sentence and can be visualized with the letter “Y”, pronounced just like the word “why”, which explains the name of the template:

Here is a comparison between my Y-statements and other popular templates:

I’d say that Y-statements do pretty well in this comparison (in terms of being lean); the five sections each in Nygard’s ADRs and the arc42 tip can get rather long. The table and a more detailed comparison appears in this WICSA 2015 paper (that also presents ADMentor). You can find a Java annotation of this six-part structure in e-ADR.

I use Y-statements in teaching. Others have picked them up too. The Cards for Analyzing and Reflecting on Doomed Software (card42) initiative by innoQ architects features them as the third⁶ of many very nice cards. The decision story approach and thesis start from them. And Herberto Graca seems to use them in the summary section of his ADR template, see his blog post “Documenting Software Architecture”. There also was a lively discussion on LinkedIn.

Good and Bad Justifications

Let’s see which arguments have a chance to pass the reviewers of your AD records (it does not matter whether you use my Y-format or another one, but a why-question should always be answered):

• “We have applied this design (pattern, technology, product) several times on successful projects that tackled similar requirements in a comparable context.”
• “We performed a Proof-of-Concept (PoC) or Proof-of-Technology (PoT) and the results were convincing; this approach will help us to achieve the required qualities.”
• “The skills to apply this technology successfully are available on the market, and using it increases the chances of being able to hire decent software engineers.”

I have also seen variations of the following “arguments” that will be received less well:

• “Everybody does it. I was told that this is a good choice.”
• “We have always done it like that.” or “I do not know any alternative, and I do not have time to look for one.”
• “Experience with this pattern, technology, and/or product will look fantastic on my resume.”

More examples and counter examples also can be found in my SATURN 2012 presentation.

Exercise: Look for some of the recent decisions made on your team. How to the decisions records do — do they answer why questions? Do the justifications convince you?

Take Aways and Next Steps

You will enjoy AD making and capturing, and be a better architect if you keep in mind:

1. Answers to “why?” questions are as important as anything else in your designs. There are no reasons not to document your key decisions and provide short but solid justifications for the options (patterns, technologies, and products) chosen.
2. Avoid pseudo rationale and killer phrases; refer to actual requirements and empirical evidence on your decision records. Do compare alternatives!
3. Do not document everything; an AD log with more than 100 entries will probably put you readers (and you) to sleep, and be really hard to maintain. Focus on the architecturally significant requirements and decisions — the ones that matter, the ones that are hard and costly to change. Some more concrete hints and definitions can be found here.
4. Many templates exist, just pick one and stick to it. Or create one — and stick to it.
5. Pick any “tool” that fits your culture and setup. In this context, a “tool” can be a plain text file, wiki, or application used for other purposes (for instance agile issue tracker or task board, UML modeling tool, version control system). Try Markdown!⁷

Where to go from here

The Y-statement part of this post is also available as a story on Medium. This and other method elements are featured in the Software/Service/API Design Practice Repository (DPR) on GitHub.

Have a look at the offerings and contact page if you would like some of your ADs reviewed — in an empathic, constructive manner: I am not the guy who asked the nasty questions in the intro story! You can also contact me if some decisions still have to be made, of course :-)

Follow-up posts cover other items in my architect toolbox. For instance, I propose a definition of done for ADs here and an architectural significance test here.

– Olaf (a.k.a. ZIO)