Documenting architecture design decisions is commonly considered a good practice and yet many teams don't take the time to write down the decisions they make. In our experience this happens for a few reasons: documentation is rejected as being too heavyweight, documentation has little influence since it is typically out of sight and out of mind, and many developers don’t know what to document. Architecture Decision Records (ADRs) address many of these problems by capturing design decisions in a simple, lightweight templates that is stored close to repositories used by stakeholders -- often in the same repository as code affected by the ADR.
In this hands-on workshop you will learn how to write effective ADRs and how to overcome road bumps teams often experience when first getting started with ADRs. By the end of this session you will have the skills you need to champion ADRs and help your team start (or improve) your design decision log.
2. Agenda
1. Theory:
• What is an Architecture Decision Record (ADR)?
• How can ADRs help your team be more awesome?
2. Practice:
• Learn how to create ADRs
16. What do we mean by “software architecture”?
Software architecture is the set of significant
design decisions about how the software is
organized to promote desired quality
attributes and other properties.
17. What do we mean by “software architecture”?
Software architecture is the set of significant
design decisions about how the software is
organized to promote desired quality
attributes and other properties.
18. Architecture is organized around structures
• Structure = Element + relation
• Element
• Fundamental building blocks
• Relation
• Description of how to combine elements
Element Element
Relation
20. Three Kinds of Structures
• Module - Design time structures
• Elements: class, module, package, layer
• Relations: uses, allowed to use, depends on
• Component and Connector (C&C) - Runtime structures
• Elements: Object, tier, process, thread, filter
• Relations: call, subscribe, pipe, publish, read
• Allocation - Map module and C&C structures to physical
elements and each other
• Elements: Server, sensor, container, Colin (a person)
• Relations: runs on, deployed to, builds, pays for
22. What do we mean by “software architecture”?
Software architecture is the set of significant
design decisions about how the software is
organized to promote desired quality
attributes and other properties.
23. What is a significant decision?
• Defines or modifies coarse grained structures
• Strongly influences...
• Quality attributes
• Costs
• Schedule
• External systems or organizations
• Dramatically alters our ability to change our minds later
• One-way door – Extremely costly to go back
• Two-way door – Easy to change your mind
24. Some examples of significant decisions
• Component X is responsible for sending email
• Because of <decision>, Foo will be more difficult to test
• We will now depend on a third-party library
• The code for ABC will move to new packages/modules
• And by accepting this technical debt we’ll ship sooner but, ….
• Because of <decision>, all devs will need to use tool Blah
26. Documenting Architecture Decisions by Michael Nygard
http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
“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.”
27. “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.”
Documenting Architecture Decisions by Michael Nygard
http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
38. Today’s Mission
• Work in pairs or small groups
• Design a “Smart Toaster”
• Perfectly toasts bread
• Voice activated
• Learns breakfast preferences of your household
• Internet connected
• Create a decision log (ADRs) for your design
39.
40. Ground Rules
• No right or wrong answers
• Watch the clock (I’ll help too)
• Ask me questions if you need help
• Fill in project gaps with your imagination (or ask)
• HAVE FUN!
42. Task #1
Meet your team! (5 minutes)
• Self-organize into pairs or small groups
• Send someone up for materials
Tips
• Introduce yourself!
• Chocolate, vanilla, or strawberry?
43. Task #2
Create a high-level design for your smart
toaster system (7 minutes)
Tips
• Sketch a picture or two
• Context diagrams are great
• Lean on your experience
• Add some buzz words – cloud, IoT, machine learning
45. Task #2
Make a decision (3 minutes)
Tips
• Use imperative voice: “We will…”
• Is it “architectural”?
• Keep it brief – can you say it one sentence?
46. Task #3
Describe the context (7 minutes)
Tips
• What exerts force influencing on the decision?
• State the context as facts
• Are there alternatives?
• Keep it brief…
48. Task #4
Outline the consequences (7 minutes)
Tips
• Consequences can be “good” or “bad”
• “As a result of this decision…”
• Think about risks
• What do you know? Did you create more work?
• Dig for at least 3 consequences
50. Task #5
Let’s write another ADR (12 minutes)
Tips
• What exerts force influencing on the decision?
• State the context as facts
• Use imperative voice for the decision: “We will…”
• Dig for at least three consequences
51. Share and Discuss
Share your ADR with another group
What was the decision?
Does the decision make sense given the context?
Can you think of more consequences?
What is awesome about the ADR?
53. Use a template
• Title
• Context
• Value neutral, describe forces at play
• Decision
• 1 sentence
• “We will ….”
• Status
• Choose one: [Proposed | Accepted | Deprecated | Superseded]
• Consequences
• New context after decision applied
• 3 – 5+, go beyond the obvious
54. # 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.
55. Easy to edit, easy to find
• A place where stakeholders can find them
• Plain text works great
• Easy to consume, easy to change
• Integrate with peer review workflow and tools
• Contextually close to where it’s used
55
56.
57. Delegate ADR Creation
• Grow the team’s design skills
• Small responsibility, little risk
• Easy to review
• Opportunity for training
• Peer review, pair, coach
57
58. Peer Review as you would Code
• Get the whole team involved
• Spread knowledge
• Allow team to make decisions without architect
58
59. Foster a documentation habit
• Architect points out when a decision is made
• “Do we need to record an ADR?”
• Track ADRs in the backlog
• Hold the team accountable
• Make templates readily available
• Host an ADR party
• Use architecture briefings
59
60. Make a decision, then document it
• Proposed decisions without consensus thrashed
during peer review
• Document and share a decision
• Remember ideas for the future
60
61. Not everything is an ADR!
• Everyone LOVES ADRs
• People will try to use them for anything and everything
• Draw pictures
• Create guidelines
• Capture other views of the system
61
62. ADR Tips and Advice
• Use a template
• Easy to edit, easy to find
• Delegate ADR creation.
• Peer review as you would code.
• Foster a documentation habit.
• Make a decision, then document it.
• Not everything is an ADR!
62
64. Get started with ADRs on your team!
You don’t need permission to start!
Step 1: Create a template
Step 2: Create your team’s first ADR
Step 3: Ask someone to review it
64
65. Architecture Decisions…
cool since at least 1997
• 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
• http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
• Michael Nygard
65
66. More Resources…
• Architecture Decision Records in Action (SATURN conference)
• Video: https://www.youtube.com/watch?v=41NVge3_cYo
• Slides: https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf
• Michael Keeling and Joe Runde
• Share the Load: Distributed Design Authority with Architecture Decision Records
• https://www.agilealliance.org/resources/experience-reports/distribute-design-authority-with-architecture-decision-
records/
• Video: https://www.agilealliance.org/resources/sessions/share-the-load-distributing-design-authority-with-lightweight-
decision-records/
• Michael Keeling and Joe Runde
• Creating, Reviewing, and Succeeding with Architecture Decision Records
• Video: https://www.youtube.com/watch?v=LFiTwqblqsk&list=PLSNlEg26NNpy1RjhlISNMRNO1gypYaXHo
• Ken Power
• Design It!
• http://bit.ly/design-it
• Michael Keeling
• https://github.com/joelparkerhenderson/architecture_decision_record
• https://adr.github.io/ 66
Had things been working well, our team would be operating like Voltron… this giant awesome machine that can do practicaly anything.
But remember, that machine is made up of individuals controlling different pieces
But it has significant limitations…
Zooming in a bit to the context, in this case we state three clear forces:
We previously decided to use a pattern
That pattern was very difficult to enforce
A framework exists to enforce this pattern
The decision is short in active voice- We will use the framework
And the consequences go into detail about all of the tradeoffs that we considered when we made this decision
Formal like a fancy dinner, not like a mathematical model.