DPR Git Pages Home — Activities Index

Activity/Technique: Architectural Decision Capturing

also known as: Decision Log(ging)

Context

Each software system has an architecture, which is defined by the set of architectural decisions made. Hopefully, these decisions are made consciously and continuously, and consensus is reached about them. This decision making progress should be recorded to avoid knowledge vaporization.

Discussion: Not all organizations can or want to follow a “products over projects” philosophy; team members come and go, e.g., external consultants. Some of these tend to apply the “I know better, why haven’t you done this and that?” tactic when joining and forget to document their legacy when leaving. Keeping a decision log current is a good safety belt in such (and similar) situations.

Purpose (When to Use and When not to Use)

As a technical team lead (architect, lead developer, product manager), I want to keep track of the results of all architecture design activities in a compact and searchable form so that newcomers can get a quick overview of the key decisions made, and the entire team (and interested external stakeholders) has a single point of reference when making follow-on decisions.

There are no reasons not to capture decisions. Two variants exist, continuous architectural decision capturing and stage-based architectural decision capturing. A stage refers to a phase or iteration, for instance a sprint in Scrum and other agile methods.

Instructions (Synopsis, Definition)

Keep a log of architectural decisions in a single place that is accessible to the entire team.

This log can, for instance, be a team-wide source modeling or code repository, a project-wide wiki, or a shared office document (word processor, spreadsheet). As the first decision to be captured, select a verbosity level for the decision log:

• At a minimum, document the decision outcome (“we chose”) and provide basic rationale (for instance, in the form of a “because” half sentence).
• On a medium level of verbosity, use one of the lean Architectural Decision Record (ADR) templates such as MADR, Y-Statements, or Nygard’s ADRs.
• If needed or desired, for instance due to external stakeholder pressure to reach certain compliance or maturity levels, apply one of the full-fledged decision modeling templates from the literature.

Examples

An example of a minimal decision capture is:

ADR-001: We decided for MySQL as our relational database in the backend 
because this database has been approved strategically by our EAM group, 
has good tool support and sufficient performance under the workload that 
we expect from the user stories to be implemented in the next 10 sprints.

Page 18 in a SAGRA 2016 keynote features a medium-verbose ADR:

See this SATURN 2010 presentation for a full-fledged example (Page 14).

Benefits vs. Effort (Expected Benefits, Skill Levels)

There are few short-term incentives for decision capturing, which has been reported to pay off in the medium to long time. Many architects report that out of all views on software architecture they provide in their software architecture documents, the decision log has been read and commented on and appreciated the most. No special skills are required; anybody who can make a decision (or contribute to a collaborative decision making effort) should be able to capture the outcome and the supporting arguments.

Comparing the two common types of definition of software architecture (components and connectors vs. set of design decisions), one can view the latter as the software engineering/architecting process equivalent of event sourcing, with all its pros and cons.

Hints and Pitfalls to Avoid

Some additional rules of thumb are:

• Stick to one template throughout a project; it is less relevant which one you pick — as long as you pick one.
• Focus on the essence of the decision, but make sure the individual ADRs and the entire decision log can serve their purpose (see above): quick orientation, long time reference.
• Assign an identifier and create minimal meta information such as decision owner/makers, status, and timestamp.
• Do not spend more time on decision capturing than on decision making (and preparing this activity).
• Establish criteria when a decision will be considered done, for instance ecADR.

From a quality point view, look for accountability (of decision makers), consistency (between decisions, between decisions and implementation artifacts), and continuity (or currentness of the design artifacts).

See InfoQ/IEEE Software article “Sustainable Architectural Design Decisions” for more tips and tricks.

Origins and Signs of Use

Origins. AD capturing has been a key element in iterative and incremental SE methods such as (R)UP and IBM UMF (and its predecessors) since the late 1990s. For instance, OpenUP has the notion of an Architecture Notebook that calls for decision capturing with a justification as a mandatory element even in minimal project documentation. The term rationale also appears in one of the first articles that defined software architecture (by Perry/Woolf). Book authors have always seen decisions to take center stage in architecture design process; see, for instance, works by SEI authors including Attribute-Driven Design (ADD) 3.0, but also patterns books and supporting material such as this rambling on the Enterprise Integration Patterns website. George Fairbanks suggests a single-sentence decision outcome overview as part of his Architecture Haiku, also used by Michael Keeling here.

Around 2014, research sub-community jumped on the topic at conferences such as WICSA and workshops such as SHARK. Decision rationale also is a mandatory element in the ISO/IEC/IEEE 42010:2011, Systems and software engineering – Architecture description. The lean and agile communities talk about deferring decisions until the last (but not the least) responsible moment. Michael Nygard suggested an ADR format that is inspired by the context-solution-consequences structure of “Alexandrian” design patterns in a blog post in November 2011. Many organizations and teams design their own templates, some of which are based on those in the literature; others are custom made, applying common sense and practices from other fields.

See the blog post“Architectural Decisions — The Making Of” for more history and context information.

Signs of Use. Filled out templates obviously indicate that decisions are made and captured explicitly. But informal justifications, for instance in the form of “we did this … because …” also qualify.

Related Content

Performing Roles and Related Artifacts (Synopsis)

Involved roles:

• Enterprise architects, program/portfolio architects
• Agile teams
• Application Architect

Related activity:

• Architecture Modeling

Produced artifact:

• Decision log with ADRs

Other Practices (Alternatives)

There are no alternatives, really. The emergent architecture community suggests not to make ADs consciously, but let the architecture emerge and evolve through frequent iterations including intense refactoring supported by measurements/experiments.

The Agile Alliance lists a Quick Design practice in its Agile Glossary. The outcome of such quick design sessions can be captured as an ADR in the decision log.

Agile Modeling has the notion of Architecture Envisioning, which yields strategic, high-impact decisions. Not even the most extreme agile team will replace is database paradigm, technology, and provider in each and every sprint.

More Information

The blog post “Architectural Decisions — The Making Of” provides examples of good and bad justifications; for instance, “will look good on my CV” does not qualify as a sound decision rationale for a technology selection decision (although it is understandable to come up with such argument).

The adr organization at GitHub compiles AD templates, as well as tools and other resources. It also hosts the MADR project. The MADR template is explained in detail in this blog post.

There are proposals for “A Definition of Done for Architectural Decision Making” and “A Definition of Ready for Architectural Decisions (ADs)”.

Data Provenance

title: "Design Practice Repository (DPR): Architectural Decision Capturing"
author: Olaf Zimmermann (ZIO)
date: "09, 02, 2024"
copyright: Olaf Zimmermann, 2020-2024 (unless noted otherwise). All rights reserved.
license: Creative Commons Attribution 4.0 International License