Seite 2: Die ADR-Methode

Eine Art der Dokumentation sind Architecture Decision Records (ADR). Sie gehen auf eine Idee von Michael Nygard aus dem Jahr 2011 zurück. Neu war dabei nicht die Idee, Entscheidungen festzuhalten, sondern die praktische Umsetzung. Zum einen liegt der Fokus auf der Entscheidung und nicht auf dem Weg dorthin. Damit unterscheiden sich Architecture Decision Records von anderen Methoden, die versuchen, die Entscheidungsfindung zu dokumentieren, indem sie beispielsweise die einzelnen Lösungsmöglichkeiten vergleichen.

Aus der Erfahrung, dass kurze Dokumente sich leichter schreiben und lesen lassen als lange, sollte für jede Entscheidung ein eigenes Dokument als Architektur Decision Record entstehen. Das Vereinfachen hilft bei der späteren Pflege.

Der konkrete Dateiname bildet sich aus dem gewählten Namen der Architekturentscheidung, gefolgt von einer eindeutigen und fortlaufenden Nummer (ID).

Jeder Datensatz setzt sich aus den folgenden Abschnitten zusammen:

• Titel (title): kurze, den Inhalt des ADR wiedergebende Beschreibung der Entscheidung.
• Kontext (context): Beschreibung der Bedingungen, die zu der Entscheidung geführt haben.
• Entscheidung (decision): Beschreibung der Entscheidung, die im Rahmen des vorher beschriebenen Kontexts erfolgt ist.
• Status (status): Position im Lebenszyklus der Entscheidung wie "proposed", "accepted", "discarded", "deprecated" oder "superseeded".
• Konsequenzen (consequences): Auflistung aller positiven und negativen Konsequenzen.

Die Beschreibung des Kontexts erfolgt ohne sprachliche Wertung, um den Lesern einen neutralen Einstieg beim Verstehen der Entscheidung zu ermöglichen. Sie sollte das zu erreichende Ziel, die technischen und andere Randbedingungen festhalten.

Eine ungewöhnlich lange Beschreibung kann ein Zeichen dafür sein, dass entweder zu viele und damit für die Nachvollziehbarkeit unnötige Details enthalten sind, oder dass es sich um mehr als eine Entscheidung handelt. In letzterem Fall ist es sinnvoll, den ADR auf mehrere aufzuteilen.

Der Architecture Decision Record für den Einsatz von Ruby als Skriptsprache könnte beispielsweise in der Datei ruby-als-skriptsprache-0001.md mit dem folgenden Inhalt festgehalten worden sein.

= ADR 0002: Ruby als Skriptsprache zum Repository Management

== Kontext

Die Git-Repositorys unseres Produkts werden auf GitHub Enterprise 
bei uns im Unternehmen gehostet. GitHub wird dabei f�r die 
Verwaltung von Issues und das Release Management verwendet. 
In unserer t�glichen Arbeit f�hrt es immer wieder zu Problemen, 
dass es in den Projekten unterschiedliche Labels f�r die Issues 
gibt und nicht �berall die gleichen Milestones verf�gbar sind. 
Das erschwert die Arbeit und Planung. Versuche Labels und 
Milestones manuell aktuell zu halten, sind immer 
wieder gescheitert.

== Entscheidung

Wir wollen die Pflege unserer Git-Repositorys in GitHub Enterprise 
und deren Metadaten �ber Skripte automatisieren, um deren 
einheitliche Konfiguration sicherzustellen und Fehler in der 
Konfiguration zu finden. Durch den Einsatz von Skripten 
kann die Pflege auch �ber unseren CI-Server automatisiert 
werden, und alle Teammitglieder k�nnen die Arbeit �bernehmen.

Dabei haben wir uns f�r Ruby als Skriptsprache entschieden. Zum 
einen weil GitHub mit Octokat eine Ruby-Library bereitstellt und 
zum anderen weil Ruby im Team gegen�ber der Kombination 
von JavaScript und Nodes.js die gr��ere Akzeptanz hat.

== Status

Accepted

== Konsequenzen

Aufgrund dieser Entscheidung muss im Team grundlegendes Ruby-
Wissen aufgebaut werden und zum Teil existierende Python- und 
Bash-Skripte ersetzt werden. Weiterhin m�ssen wir uns auf die zu 
nutzenden Labels  f�r Issues einigen und anschlie�end alte Labels 
durch neue ersetzen.

---

Der beispielhafte Architecture Decision Record zeigt auf den zweiten Blick auf, wie schwer das Abgrenzen von Entscheidungen ist. Genau genommen enthält er zwei einzelne Entscheidungen: Die erste ist der Einsatz von Skripten für das Repository-Management und die zweite die Wahl von Ruby als Skriptsprache. Wie scharf die Trennung erfolgen soll, müssen Teams im Einzelfall entscheiden. Dabei gilt es, die passende Balance zwischen Aufwand und Nutzen zu finden.

Blick in die Werkzeugkiste

Inzwischen existieren einige Tools rund um Architecture Decision Records, wie ein Blick auf die Site der ADR-GitHub-Organisation zeigt. Nat Pryce hat eine Sammlung von ADR-Tools als Bash-Skript-Sammlung geschrieben, die sich direkt auf den Vorschlag von Michael Nygard beziehen. Sie lässt sich unter anderem als Tarball herunterladen. Nach dem Entpacken und Einbinden des Verzeichnisses in den Pfad lässt sich folgendermaßen der erste ADR erzeugen:

> adr init

Der Befehl initialisiert das Verzeichnis, in dem das Tool die ADRs ablegt. init erzeugt dabei den ersten ADR, der die Entscheidung dokumentiert, Architekturentscheidungen mit ADR zu dokumentieren.

Weitere ADRs lassen sich beispielsweise wie folgt anlegen:

> adr new Ruby als Skriptsprache zum Repository Management

Die ADR-Tools legen daraufhin die Grundstruktur als Vorlage an, die Teams mit der eigentlichen Entscheidung füllen müssen.

Das Anlegen von Textdateien und das Hochzählen einer laufenden Nummer sind freilich kein Hexenwerk, aber die ADR-Tools bieten zahlreiche Annehmlichkeiten. Unter anderem aktualisieren sie beim Anlegen eines neuen ADR Einträge, die damit ungültig werden. Wenn die Entscheidung für Ruby die ADR-Nummer 2 hat und im Beispielszenario später die Automatisiserung des Repository Managements stattdessen mit Node.js erfolgen soll, lässt sich folgender Befehl verwenden:

> adr new -s 2 NodeJS als Skriptsprache zum \
  Repository Management

Die ADR-Tools setzen dabei den Status des ADR 2 auf "superseeded" und verlinken den neuen und den alten ADR miteinander.

Deutlich wichtiger als das Tooling zur Verwaltung von ADRs ist das Format, in dem die Einträge geschrieben sind. Das kann eine einfache Textdatei sein, aber ebenso gut lassen sich ADRs über ein Wiki verwalten. Die auf der Seite der ADR-GitHub-Organisation aufgeführten Tools verwenden hauptsächlich Asciidoctor und Markdown als Markup Language. Versionsverwaltungssyteme wie GitLab oder GitHub zeigen beide Formate an, sodass Entwickler ADRs über eine Weboberfläche ohne zusätzliche Werkzeuge lesen können.

Gut dokumentiert

Dokumentation ist nur gut, wenn sie das richtige Wissen vermittelt. Architecture Decision Records sollen helfen, getroffene Entscheidungen zu kommunizieren und nachvollziehbar niederzuschreiben. Dazu gehört immer, dass mit der Entscheidung zu erreichende Ziel zu benennen.

Ob ein ADR das schafft, lässt sich daran überprüfen, ob er Antwort auf die fünf "W"-Fragen gibt: Wann? Wer? Warum? Wozu? Was? Lassen sich die Fragen schlüssig aus dem ADR heraus beantworten, besteht eine gute Chance, dass er seinen Zweck erfüllt. Optimalerweise beantwortet ein unbeteiligter Reviewer, der nicht an der Entscheidung mitgewirkt hat, die Fragen aus dem ADR heraus.

Dokumentation ist kein Selbstzweck. Daher gibt es in der Praxis gute Gründe, sich bewusst dagegen zu entscheiden. Wenn nicht alle Beteiligten den Willen zur Dokumentation teilen, ist es wenig effizient, sofern nur Einzelne sich des Themas annehmen. Gegen eine Dokumentation spricht auch, wenn Teams nur die unkritischen Entscheidungen dokumentieren können, denen jeder zustimmt, es aber nicht schafft, für die wichtigen Themen gemeinsam getragene Entscheidungen zu treffen.