Architecture Decision Records (ADRs)
Helpful now, invaluable later
Architectural decision
Design decisions that address architecturally significant requirements
hard to make and/or costly to change
Consider a structural change
- How costly will this change be in time, money, and effort?
- Does this change add complexity to the system, or simplify it?
- Will this change require more changes?
- What are the security implications of this change?
Discussion
Oral history
PR / issues
Limits of Oral History
- Short reach
- Time consuming to share
- Changes over time
Before long, important details are forgotten
Discussion
Documentation?
Oral history
PR / issues
Title Text
- Bullet One
- Bullet Two
- Bullet Three
An ideal documentation
- Low barrier to entry
- Value-adding, useful
- Small, modular documents have at least a chance at being updated
What is the least we can document
and still remain effective?
is it easy to track changes? 🤔
Why to track a decision?
Without understanding the motivation behind certain decision, a new person coming on to a project has only two choices:
Blindly accept the decision
Blindly change it
Discussion
ADR 🙂
Oral history
PR / issues
ADR
“An architecture decision record is a short text file in a format similar to an Alexandrian pattern that describes a set of forces and a single decision in response to those forces.”
Rationale
Architecturally significant change
Decision
Consequences
Status
Context
How would it look?
- Title
- Context
- Design decision
- Rationale
- Status
- Consequences
Template
- Markdown
- Direct language
- Brief, 1-2 pages max
- Stored with the code (peer review)
# ADR N: Brief Decision Title
Context goes here. Describe the forces at play, including technological, political,
social, and project local. These forces are likely in tension, and should be called
out as such. The language in this section is value-neutral. It is simply describing
facts. Rationale should be self-evident from the context
## Decision
This section describes our response to these forces. It is stated in full sentences,
with active voice. "We will ...“
## Status
choose one: [Proposed | Accepted | Deprecated | Superseded]
if deprecated, include a rationale. If superseded, include a link to the new ADR
## Consequences
Describe the resulting context, after applying the decision. All consequences should
be listed here, not just the "positive" ones. A particular decision may have positive,
negative, and neutral consequences, but all of them affect the team and project in the
future.Record any architecture design decision
- Alters externally visible system properties
- Modifies a public interfaces
- Directly influences a high priority quality attribute
- Includes or removes a dependency
- Direct result of new information about a constraint
- Accepts strategic technical debt
- Changes the general structures of the system
- Forces developers to change their development approach
Involve the whole team
- Spread knowledge 🙂
- Easy to delegate (opportunity for training)
- Avoiding rework
- Impact on quality (manage technical debt)
missed the discussion meeting? no problem
Further info
Further info
- Related work
1997: Architecture in Practice, first edition. Len Bass, Paul Clements, Rick Kazman
2002: Documenting Software Architecture: Views and Beyond, first edition. Paul Clements et al
2005: Architecture Decisions: Demystifying Architecture. Jeff Tyree and Art Akerman
2009: The Decision View's Role in Software Architecture Practice. Phillipe Krutchten
2011: A documentation framework for architecture decisions. Uwe Van Heesch, Paris Avgerioum, and Rich Hilliard
2011: Documenting Architecture Decisions. Michael Nygard