Architectural Decisions — The Making Of [Link]
html
Share
ZIO Contact Consulting IT architect and part time lecturer.
Architectural Decisions — The Making Of
Apr 27, 2020 (Updated: Mar 2, 2021)
Reading time: 12 minutes
Content Outline
1. Motivation
2. A Bit of History
3. Y-Statements and other Templates
4. Good and Bad Justi�cations
5. Take Aways and Next Steps
Architectural Decisions (ADs) have been answering “why” questions about design options since the inception
1 of 7 3/31/2022, 3:38 PM
Architectural Decisions — The Making Of [Link]
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 e�ort, and only crisp and sound justi�cations will convince the reader.
Let’s see how to get there.
Motivation
Let’s start with an example, made up from a true story:1
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 e�cient?”
• “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 �nal 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/di�erentiator phase. In the 1990s, ADs received less attention than notations such as UML or ADLs,
but they were de�nitely there already:
◦ The term “rationale” was introduced as one of three components of any software architecture in a
research paper in 1992.2
◦ Software vendors and professional services �rms established templates for their sta�, 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.3
◦ The commercial Rational Uni�ed Process (RUP)4 also included a decision guideline, which has
become a bit hard to �nd 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
2 of 7 3/31/2022, 3:38 PM
Architectural Decisions — The Making Of [Link]
practices with the public:
◦ A Groningen workshop in 2004 kicked an intensive period of research o�. 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-�lled 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 de�nitions
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 �ltering advice (and
clari�es many other concepts).
◦ Academic conferences such as WICSA and ECSA and scienti�c 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
3 of 7 3/31/2022, 3:38 PM
Architectural Decisions — The Making Of [Link]
�rst 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 e�ort of �lled out, full-�edged 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 �t
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 In the context of the Web shop service,
2 facing the need to keep user session data consistent and current across shop instances,
3 we decided for the Database Session State Pattern
4 and neglected Client Session State or Server Session State
5 to achieve cloud elasticity,
6 accepting that a session database needs to be designed, implemented, and replicated.
Each template element appears on one line in the above example:5
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: bene�ts, the full or partial satisfaction of the requirement,
6. accepting that: drawbacks, impact on other properties/context and e�ort/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:
4 of 7 3/31/2022, 3:38 PM
Architectural Decisions — The Making Of [Link]
I’d say that Y-statements do pretty well in this comparison (in terms of being lean); the �ve 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 �nd 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 Re�ecting on
Doomed Software (card42) initiative by innoQ architects features them as the third6 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:
5 of 7 3/31/2022, 3:38 PM
Architectural Decisions — The Making Of [Link]
• “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 justi�cations 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 justi�cations 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 signi�cant requirements and
decisions — the ones that matter, the ones that are hard and costly to change. Some more concrete hints
and de�nitions 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 �ts your culture and setup. In this context, a “tool” can be a plain text �le, wiki, or
application used for other purposes (for instance agile issue tracker or task board, UML modeling tool,
version control system). Try Markdown!7
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 o�erings 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 de�nition of done for ADs
here and an architectural signi�cance test here.
– Olaf (a.k.a. ZIO)
1. stakeholder names removed and older technology included on purpose ↩
2. Perry, Dewayne & Wolf, Alexander: Foundations for the Study of Software Architecture. ACM SIGSOFT
Software Engineering Notes, October 1992. The other two parts are “elements” (components, connectors)
and “form” (properties and their qualities). ↩
3. I will use this form and not architecture decisions simply because I am used to it from that time. The
6 of 7 3/31/2022, 3:38 PM
Architectural Decisions — The Making Of [Link]
ARC-100 work product was part of the IBM Systems Integration/Global Services Method since 1998 (at
least). ↩
4. For more information on RUP, see Wikipedia and this overview article. ↩
5. George Fairbanks provided inspiration with his Architecture Haikus; decision outcome and its
consequences are part of his one-napkin documentation approach. ↩
6. ok, the cards probably are ordered alphabetically ↩
7. IMHO, usage of spreadsheets to capture structured text and design results is a warning sign, and smells
like an instance of the law of the instrument bias: if the hammer is your favorite (or only) instrument, all
problems will appear as nails to you. ↩
Category: Practices
Tags: #architectural decisions #documentation #software architecture #template
Previous: Technical Writing Tips and Tricks
Next: MAP Retrospective and Outlook
Explore Blog by category
index (5) authoring (6) practices (11) patterns (3) misc (1)
Copyright © 2022 Olaf Zimmermann (ZIO). All rights reserved. Terms and
Conditions apply.
Based on the Mediumish Jekyll Theme.
7 of 7 3/31/2022, 3:38 PM
