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.
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
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?
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€
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