Architecture Decision Records

Bei der täglichen Suche nach Lösungen müssen wir oft Kompromisse eingehen, denn selten gibt es die eine richtige Lösung. Wir müssen die Vor- und Nachteile mehrerer Optionen abwägen und dann eine Entscheidung treffen. Um besonders wichtige Entscheidungen zu dokumentieren und nachvollziehbar zu machen, verwenden viele Teams Architecture Decision Records (ADRs).

Architecture Decision Records sind Dokumente, die wichtige Architekturentscheidungen in einem Projekt festhalten. Sie beschreiben die getroffene Entscheidung, die Gründe dafür und die in Betracht gezogenen Alternativen und sind dadurch eine wertvolle Ressource für die langfristige Dokumentation.

ADRs machen den Entscheidungsprozess und die involvierten Personen transparent. Aus dieser Transparenz und dem gewonnenen Wissen können wertvolle Vorteile gezogen werden.

Nachvollziehbarkeit: Es kann vorkommen, dass Außenstehende Lösungen in Frage stellen und alternative Optionen vorschlagen, die bereits bewertet wurden. ADRs helfen, den Abwägungsprozess zu dokumentieren und für andere nachvollziehbar zu machen, warum eine Option gewählt wurde.

Wiederverwendbarkeit: Die Dokumentation hilft auch anderen unabhängigen Teams, die ähnliche Entscheidungen treffen müssen. Andere Teams können die Entscheidungen und die zugehörigen Dokumente einsehen und in ihre Entscheidungsfindung einbeziehen.

Strukturierte Kommunikation: ADRs geben eine qualitative Struktur vor, die hilft, die Kommunikation mit Share- und Stakeholdern auf eine gemeinsame Basis zu stellen. Treffen zur Entscheidungsfindung beginnen nicht bei null, sondern führen durch die einheitliche Strukturierung schneller zu einem Ergebnis.

Onboarding: Das in den ADRs festgehaltene Wissen ist wertvoll bei der Einarbeitung neuer Teammitglieder oder bei der Übergabe von Projekten. Sie helfen, die Architektur und die Wahl der Werkzeuge zu verstehen und geben einen guten Überblick über die wichtigsten Komponenten.

ADRs bestehen aus verschiedenen Abschnitten. In einem Metadaten-Abschnitt werden die beteiligten Personen, das Datum und die verknüpften Ressourcen festgehalten. Der Entscheidungsteil enthält Informationen über den Kontext, die betrachteten Optionen mit ihren Vor- und Nachteilen sowie die endgültige Entscheidung.

Für den ersten Aufschlag kann das DACI-Framework genutzt werden.

„DACI“ setzt sich aus den Anfangsbuchstaben der folgenden Metadaten zusammen:

Driver: Wer hat die Entscheidungsfindung verantwortet?

Approver: Wer hat die Entscheidung getroffen?

Contributor: Wer hat Fachwissen eingebracht und die Entscheidungsfindung unterstützt?

Informed: Welche Personen wurden nach der Entscheidung informiert?

Für die eigentliche Entscheidung sind folgende Punkte besonders wichtig:

Kontext: Hier wird der Kontext der Entscheidung festgehalten. Warum soll die Entscheidung getroffen werden? Welche Auswirkungen hat die Entscheidung und welches Ziel soll erreicht werden?

Betrachtete Optionen: Um die evaluierten Optionen festzuhalten, werden sie mit ihren Vor- und Nachteilen dokumentiert. Verweise auf bewährte Verfahren und Entscheidungen anderer Teams können bei der Auswahl und Gewichtung helfen.

Entscheidung: Natürlich muss auch die Entscheidung selbst festgehalten werden. Dabei ist es wichtig herauszustellen, welche Argumente besonders ausschlaggebend waren und warum diese Entscheidung getroffen wurde. 

Referenzen/Artefakte: Ein ADR muss übersichtlich gehalten werden. Entscheidungen, die in die technische Tiefe gehen, erfordern von Zeit zu Zeit genauere Beschreibungen und Dokumentationen. Diese können als Referenz im ADR hinterlegt werden und stehen so bei Bedarf zur Verfügung.

Wenn diese Faktoren berücksichtigt werden, können Entscheidungen transparent kommuniziert werden. Je nach Anwendungsbereich und Dokumentationssystem können weitere Faktoren ergänzt werden. Für die konkrete Umsetzung stehen neben dem DACI-Framework weitere Vorlagen zur Verfügung.

Neben dem in Confluence integrierten DACI-Framework gibt es zahlreiche weitere Templates, die sich auf ADR beziehen. Die folgende Github-Seite bietet einen guten Überblick und Links zu den einzelnen Templates: 

Auch andere Unternehmen setzen das ADR Framework ein: