Dokumentation gehört oft nicht zu den Lieblingsaufgaben im Softwareentwicklungsalltag. Das resultiert in vielen Fällen daraus, dass nicht klar ist, warum etwas dokumentiert werden sollte. Der in der Praxis gelebte Ansatz einen Dokumentationsort, zum Beispiel in Form eines Wikis, ist zum Scheitern verurteilt. Entweder es wird kaum dokumentiert oder zu viel und es wird schwer Informationen zu finden, die man sucht. Ein leichtgewichtiger Ansatz ist arc42, bei dem je nach Bedarf die vorgegebenen Unterpunkte ausgefüllt werden. Dort werden im Unterpunkt neun Entwurfsentscheidungen dokumentiert, also genau die Entscheidungen, die die Softwarearchitektur entscheidend prägen. Die Auswirkungen von nicht dokumentierten Entscheidungen gehen von immer wiederkehrenden Diskussionen, bis hin zu fehlerhaften Folgeentscheidungen die das Projekt zum Scheitern bringen können. Doch wie können viele Entscheidungen effizient und nachvollziehbar dokumentiert werden? In diesem Vortrag wird ein kompaktes Format namens Architecture Decision Records (ADR) vorgestellt und gezeigt, wie sie effizient eingesetzt werden können. Neben Kleinigkeiten wie der Titelvergabe für eine ADR wird ein Lösungsvorschlag aufgezeigt, um bei einer großen Sammlung von Entwurfsentscheidungen (>50) nicht den Überblick zu verlieren. Dabei kommt der Docs-As-Code Ansatz mit AsciiDoc und JBake zum Einsatz, mit dem die technische Architektur in einer Microsite gerendert wird. Durch Tagging und eine effiziente Suche, wird die Dokumentation nicht nur lebendig, sondern zum täglichen Arbeitsmittel.

1. Johannes Dienst (@JohannesDienst)
Effizient arbeiten mit
Architecture Decision
Records (ADR)

2. Johannes Dienst @JohannesDienst2
Produktentwicklung
• Single-Source-of-Truth für Content
• Omni-Channel Ausspielung
• Viele Entscheidungen
• Was ist Produkt? - Was ist Projekt?
• Diskussionen um Entscheidungen

3. Johannes Dienst (@JohannesDienst)3
Was ist eine Entwurfsentscheidung?
Code-Ebene
Bubble-Sort
statt
Merge-Sort
Solution-Ebene
Circuit Breaker
Applikations-Ebene
Hystrix

4. Johannes Dienst (@JohannesDienst)4 https://arc42.de/

5. Johannes Dienst (@JohannesDienst)5

6. Architecture Decision Record (ADR)
Johannes Dienst (@JohannesDienst)6
Titel
Entscheidung
Status
Kontext / Hintergrund
Konsequenz(en)
Alternativen

7. Johannes Dienst (@JohannesDienst)7
ADR-3: Staging-Umgebung für CMS
Entscheidung
Wir verwenden kein Push-Publishing bzw. verschiedene Staging Umgebungen.
Status
BESCHLOSSEN
Kontext
Es wird eine Lösung gesucht um Skalierbarkeit für das gesamte System sicherzustellen.
Konsequenzen
Änderung der System-Architektur notwendig
• Abbau der beiden Public Instanzen
• Dekonfigurieren von Push Publishing
Es wird keine Umgebung zur Verfügung gestellt, auf der Content gepushed wird
Alternativen
Cluster-Lösung
• Betrieb des CMS im Cluster
Push Publishing
• Verwendung für mehrere Stages

8. Anatomie einer ADR - Titel
Johannes Dienst (@JohannesDienst)8
Titel
Entscheidung
Status
Kontext / Hintergrund
Konsequenz(en)
Alternativen
Kurze Nomen-Phrasen

9. Anatomie einer ADR - Titel
Johannes Dienst (@JohannesDienst)9
Titel
Entscheidung
Status
Kontext / Hintergrund
Konsequenz(en)
Alternativen
• Aktive Sprache
• Knappe Erklärung
• Wir implementieren…

10. Anatomie einer ADR - Titel
Johannes Dienst (@JohannesDienst)10
Titel
Entscheidung
Status
Kontext / Hintergrund
Konsequenz(en)
Alternativen
• Beschlossen
• Offen
• Widerrufen

11. Anatomie einer ADR - Titel
Johannes Dienst (@JohannesDienst)11
Titel
Entscheidung
Status
Kontext / Hintergrund
Konsequenz(en)
Alternativen
• Fakten beschreiben
• Oft politisch,
technologisch,
strategisch,
soziologisch …
• Alles einbeziehen
• Wirklich ALLES

12. Anatomie einer ADR - Titel
Johannes Dienst (@JohannesDienst)12
Titel
Entscheidung
Status
Kontext / Hintergrund
Konsequenz(en)
Alternativen
• Gliedern in:
Positiv, Negativ, Neutral
• Ganze Sätze

13. Anatomie einer ADR - Titel
Johannes Dienst (@JohannesDienst)13
Titel
Entscheidung
Status
Kontext / Hintergrund
Konsequenz(en)
Alternativen
• Mindestens zwei
Auswahlmöglichkeiten
• Vor- und Nachteile
beschreiben

14. Johannes Dienst (@JohannesDienst)14
Entscheidungslog
Icons made by Freepik and Smashicons from www.flaticon.com
ADR - 001
ADR - 002
ADR - 003
.
.
.
Extend System B to implement
interactive approval processing
Keine kundenspezifischen
Acceptance-Tests
Module Structure & Loading

15. Johannes Dienst (@JohannesDienst)15
Große Entscheidungslogs?
Icons made by Freepik and Smashicons from www.flaticon.com
Gute Titel!
Noch bessere Titel!
Habe ich schon gute Titel
erwähnt?

16. Johannes Dienst (@JohannesDienst)16
Große Entscheidungslogs?
Icons made by Freepik and Smashicons from www.flaticon.com
https://github.com/mrwilson/adr-viewer

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

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

19. Johannes Dienst (@JohannesDienst)19
Entscheidungen?

20. Johannes Dienst (@JohannesDienst)20
Entscheidungen?

21. Johannes Dienst (@JohannesDienst)21
Tagging

22. Johannes Dienst (@JohannesDienst)22
Technik hinter der Microsite
Icons made by Freepik, Good Ware and Smashicons from www.flaticon.com
docToolchain

23. Johannes Dienst (@JohannesDienst)23
Technik hinter der Microsite
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
master
adr-042

24. Johannes Dienst (@JohannesDienst)24
Weitere Vorteile - Transparenz von Architekturentscheidungen
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com

25. Johannes Dienst (@JohannesDienst)25
Weitere Vorteile – Anbindung an interne Suchmaschine

26. Learnings
Johannes Dienst (@JohannesDienst)26
ADRs als Log von Entscheidungen -> Nachvollziehbarkeit
Schwierig zu verwalten bei vielen Architekturentscheidungen
Docs-as-Code mit Microsite für ADR-Log
Durchsuchbarkeit durch Tagging
Transparenz von Architekturentscheidungen durch Anbindung an
interne Suchmaschine

27. Welche zwei Fragen sind noch offen?
Johannes.Dienst@DeutscheBahn.com
@JohannesDienst

28. Johannes Dienst @JohannesDienst28
https://github.com/joelparkerhenderson/architecture_decision_record#suggestions-for-writing-good-adrs
Weiterführende Links
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