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.

1. Getting Started with
Architecture Decision Records
Michael Keeling
LendingHome
@michaelkeeling
Code & Supply
Architecture Meetup #5

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

3. A “100% hypothetical”
conversation with a
teammate…

4. I’m a leg!

5. We need to make decisions so
we can move forward.
We can’t move forward fast unless
everyone understands the decision.

7. X

8. Oral history is a great way to share
design decisions especially while we’re
still exploring the architecture.

9. Limits of Oral History
Short reach
Changes organically
Time consuming to share
Dies without constant attention

10. Eventually we need to write
something down.

11. How do we share decisions?
Code
Wikis
Documents
Email
Slack

12. How do we share decisions?
Code
Wikis
Documents
Email
Slack
Never erase the whiteboards

13. Just writing something down
isn’t enough.
We’ve gotta capture
the “right” things.

14. ARCHITECTURE
DECISION
RECORDS

15. Let’s start with the “A”….

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

19. Same basic elements, many arrangements

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

21. D is for Decision

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

25. And that brings us to the “R”….

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

28. Architecture Decision Record (ADR)
28
Context
Decision
Consequences

29. 29

30. 30

31. 31

32. 32

33. 33
Capturing design decisions as we
make them lets us build a
decision log over time…

34. 34

35. 35
Plain, direct language
Brief, 1-2 pages max
Markdown
Stored with the code

36. Benefits of ADRs
Simple
Easy to teach
Discoverable
Low barrier to entry
Easy to ramp up over time

37. PRACTICE TIME!

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

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! 

41. Example:

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

44. Your first ADR…

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…

47. Share and Discuss
What’s the context?

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

49. Share and Discuss
Decision + 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?

52. SOME PARTING
PRACTICAL ADVICE

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

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

63. WRAP UP

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

67. Silver
Toolbox

68. Thank you!
Michael Keeling
@michaelkeeling
neverletdown.net
Buy Design It! now at
http://bit.ly/design-it