From Architectural Decisions to Design Decisions
If architectural decision records are so useful to capture software design rationale, why not extend their scope? This is Part 1 of a two-part story; Part 2 goes from software design decision to strategic ones and any decision.
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:
- Architectural decisions directly or indirectly determine the non-functional characteristics (or qualities) of a system (think -ilities or consult this post for examples).
- 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.
- Architectural decisions concern a software system as a whole, or one or more of the core components of such system (whatever the “core” is).
Examples are the selection of programming languages and tools, of architectural patterns, of integration technologies and of middleware assets. An earlier story identifies some more core decisions. Note that those already go into organizational matters, for instance by asking “What governance structure should be in place for a product?”. This indicates that there is no hard line between architecture design and other 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 story too) uses seven criteria to assess significance quickly:
- Impact on business value and risk?
- Key stakeholder concern?
- Unusual quality-of-service requirement (at least one order of magnitude more advanced than previous ones)?
- About external dependencies that are uncontrollable, unpredictable or unreliable?
- Cross-cutting, system-wide impact?
- First-of-a-kind character (novelty for team)?
- 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 yet another story, 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), a topic for a future post. 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?
Design Decision Capturing
I follow Grady Booch in that all architecture is design but not all design is architecture. 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 several of the seven test criteria: The product owner will be unhappy if users walk away due to a crude query syntax; the open source contributors probably 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 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 they do not qualify as architecturally significant, is useful and possible.
Can we take another step now, from design to information technology in general (or even further)? Part 2 investigates.
I hope you liked this part of the story. If so, please consider to clap for it.
– Olaf (a.k.a. ZIO) with input from Oliver Kopp
Note: This post and Part 2 are also available in a single post on my personal blog called “ADR = Any Decision Record? Architecture, Design and Beyond”.
© Olaf Zimmermann, 2021. All rights reserved.
