Architecture Decision Records (ADRs)
Helpful now, invaluable later
Design decisions that address architecturally significant requirements
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?
PR / issues
Limits of Oral History
- Short reach
- Time consuming to share
- Changes over time
PR / issues
- 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
PR / issues
“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.”
How would it look?
- Design decision
- Direct language
- Brief, 1-2 pages max
- Stored with the code (peer review)
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
- 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
By Juan Rodríguez