The document discusses documenting architecture decisions using Architecture Decision Records (ADRs). It provides examples of ADR templates including title, decision, status, context/background, consequences, and alternatives sections. It discusses advantages of ADRs such as traceability, transparency, and reducing costs from architecture decisions. It also discusses managing large decision logs, using docs as code with microsites to tag and search decisions, and connecting ADR logs to internal search engines for further transparency. Two questions remaining open are about managing many architecture decisions and the technology used to build the microsite for the ADR log.

1. Johannes Dienst (@JohannesDienst)
Work efficiently with
Architecture Decision
Records (ADR)

2. Johannes Dienst @JohannesDienst2
Why You Need to Document Decisions
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com

3. Johannes Dienst @JohannesDienst3
Why You Need to Document Decisions
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
?

4. Johannes Dienst @JohannesDienst4
Product Development
• Single-Source-of-Truth for Content
• Omni-Channel
• A lot of decisions
• What is product feature? What not?
• Arguments about decisions
DB Content Hub

5. Johannes Dienst (@JohannesDienst)5
What is a Design Decision?
Code
Bubble-Sort
vs
Merge-Sort
Solution
Circuit Breaker
Application
Hystrix

6. Johannes Dienst (@JohannesDienst)6 https://arc42.org

7. Johannes Dienst (@JohannesDienst)7

8. Architecture Decision Record (ADR)
Johannes Dienst (@JohannesDienst)8
Title
Decision
Status
Context / Background
Consequences
Alternatives

9. Johannes Dienst (@JohannesDienst)9
ADR-003: Staging- vs Cluster-Environment for CMS
Decision
We use two environments (IAT, Prod). These are built as a cluster each.
Status
ACCEPTED
Context
A solution is sought to ensure scalability for the entire system. The goal is to potentially serve dozens of customers with
thousands of requests per second.
Consequences
Change of system architecture necessary
• Deconstruction of the two public instances
• Deconfiguring Push Publishing
No environment is provided on which content is pushed
Alternatives
Cluster solution
• Operation of the CMS in a cluster
Push publishing
• Use for multiple stages

10. Anatomy of an ADR - Title
Johannes Dienst (@JohannesDienst)10
Title
Decision
Status
Context / Background
Consequenc(es)
Alternatives
Short noun phrases

11. Anatomy of an ADR - Decision
Johannes Dienst (@JohannesDienst)11
Title
Decision
Status
Context / Background
Consequences
Alternatives
• Active language
• Brief explanation
• We implement…
• We use…

12. Anatomy of an ADR - Decision
Johannes Dienst (@JohannesDienst)12
Title
Decision
Status
Context / Background
Consequences
Alternatives
• Decided
• Open
• Revoked
• Replaced

13. Anatomy of an ADR - Context
Johannes Dienst (@JohannesDienst)13
Title
Decision
Status
Context / Background
Consequences
Alternatives
• Describe facts
• Often political,
technological, strategic,
sociological…
• Include everything
• EVERYTHING

14. Anatomie einer ADR - Titel
Johannes Dienst (@JohannesDienst)14
Title
Decision
Status
Context / Background
Consequences
Alternatives
• Structure:
Positive
Negative
Neutral
• Complete sentences

15. Anatomie einer ADR - Titel
Johannes Dienst (@JohannesDienst)15
Title
Decision
Status
Context / Background
Consequences
Alternatives
• At least two choices
• Describe advantages
and disadvantages

16. Johannes Dienst (@JohannesDienst)16
Decision Log
Icons made by Freepik and Smashicons from www.flaticon.com
ADR - 001
ADR - 002
ADR - 003
.
.
.
Extend System B to implement
interactive approval processing
No customer-specific
acceptance tests
Module Structure & Loading

17. Johannes Dienst (@JohannesDienst)17
Large Decision Logs
Icons made by Freepik and Smashicons from www.flaticon.com
Good Titles!
Better Titles!
Have I already mentioned
good titles?

18. Johannes Dienst (@JohannesDienst)18
Large Decision Logs?
Icons made by Freepik and Smashicons from www.flaticon.com
https://github.com/mrwilson/adr-viewer

19. Johannes Dienst (@JohannesDienst)19
Docs as Code
Icons made by Freepik and Smashicons from www.flaticon.com

20. Johannes Dienst (@JohannesDienst)20
Docs as Code

21. Johannes Dienst (@JohannesDienst)21
Microsite

22. Johannes Dienst (@JohannesDienst)22
Decisions?

23. Johannes Dienst (@JohannesDienst)23
Tagging

24. Johannes Dienst (@JohannesDienst)24
Technology Behind the Microsite
Icons made by Freepik, Good Ware and Smashicons from www.flaticon.com
docToolchain

25. Johannes Dienst (@JohannesDienst)25
Technology Behind the Microsite
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
main
adr-042

26. Johannes Dienst (@JohannesDienst)26
Further Advantages - Transparency of Architecture Decisions
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com

27. Johannes Dienst (@JohannesDienst)27
Costs of an Architecture Decision
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
Decision: How to store Secrets?
5 Person Days * 1000€ = 5000€
300 Teams * 5000€ = 1500000€

28. Johannes Dienst (@JohannesDienst)28
Further Advantages - Connection to Internal Search Engine
sitemap.xml

29. Learnings
Johannes Dienst (@JohannesDienst)29
ADRs as log of decisions-> Traceability + Transparency
Difficult to manage for a lot of architecture decisions
Docs as Code with microsite for ADR-Log
Searchability through tagging
Transparency of architecture decisions through connection to internal
search engine

30. Which two questions are still open?
Johannes.Dienst@DeutscheBahn.com
@JohannesDienst

31. Johannes Dienst @JohannesDienst31
Links
https://github.com/joelparkerhenderson/architecture_decision_record#suggestions-for-writing-good-adrs
https://kevinjalbert.com/start-now-architecture-decision-records/
https://github.com/mrwilson/adr-viewer
https://adr.github.io/
https://personal.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf