weidner/dokument/

ADR - Architecture Decision Records

In den 90er Jahren, als ich noch als Softwareentwickler arbeitete, fing ich in einer Firma an, die als eine der ersten Lösungen für das Internet-Banking anbot und einführte. Es war die zweite Firma, in der ich als Softwareentwickler arbeitete und ich war bereits einige Zeit Mitglied im ACM, hatte mich der SIGSOFT angeschlossen und eine hohe Meinung von meiner Kompetenz. Zumindest von meiner Kompetenz, Zweifel an den Entscheidungen anderer auszusprechen.

Irgendwann warf ich einen Blick auf die von dieser Firma verwendeten, selbst entwickelten Protokolle und Datenstrukturen und sah sofort, dass da etwas nicht stimmte. Ich fragte, wie viel "Erfahrung" die Schöpfer dieser Datenstrukturen mit der Entwicklung von Protokollen hatten und zeigte und begründete die von mir entdeckten Fehler. Der ursprüngliche Entwickler war für einige Zeit nicht erreichbar und ich war sehr überzeugend in meiner Argumentation, also passten wir die Datenstrukturen an.

Als er wieder zurück kam, war ich darauf gefasst, ihm meine Argumente darzulegen und den Ruhm als Retter des Internet-Bankings einzuheimsen. Stattdessen machte er die Änderungen rückgängig. Das war für mich nicht leicht zu verarbeiten, jedoch zeigte er mir, dass er an meine Bedenken bereits gedacht hatte und wie sein Entwurf diesen begegnete. Dann ging es mit dem Tagesgeschäft weiter und ich verlor die Sache aus den Augen.

Diese uralte Geschichte, bei der ich nicht einmal ein gutes Bild abgegeben hatte zeigt sehr klar ein generelles Problem, dass mir später, auch nachdem ich längst zur Systemadministration gewechselt war, wieder und wieder begegnet ist.

Das Problem, dass - wenn überhaupt - Datenstrukturen, Protokolle und Vorgehensweisen dokumentiert werden, aber selten die Gründe, warum genau diese verwendet werden und keine anderen. Und genau das macht es schwer ein System zu ändern, wenn es nötig wäre, beziehungsweise vor Änderungen zu schützen, die schädlich wären.

Ich bin vor langer Zeit auf einen Satz von Tom van Vleck gestoßen, der sinngemäß lautet: Wenn dein Vorgehen nicht dokumentiert ist, hast Du es nicht gemacht. (If your procedure isn't documented, you didn't do it.)

In diesem Sinne versuche ich sehr vieles, was ich tue, aufzuschreiben, um mich später daran zu erinnern

a) dass ich etwas schon gemacht habe (das könnte ich auch an den Resultaten sehen),

b) wie ich etwas gemacht habe (das erspart mir oder jemand anderem, es noch einmal herausfinden zu müssen).

Was ich eher selten dokumentiert habe, ist

c) warum ich etwas gemacht habe.

Und diese Erkenntnis ist mir erst im Laufe der Zeit gekommen, vielleicht weil ich "am liebsten nichts" mache und dabei hilft mir die Frage: warum soll oder will ich etwas Bestimmtes tun.

Nun hat mich vor einiger Zeit ein Bekannter auf einen Artikel von Michael Nygard hingewiesen, in dem Nygard genau das eingangs erwähnte Problem in der Softwareentwicklung anspricht und Architecture Decision Records (ADR) als eine mögliche Abhilfe zeigt.

Was sind Architecture Decision Records?

Im wesentlichen sind ADR Templates mit deren Hilfe grundlegende Architekturentscheidungen strukturiert festgehalten werden, so dass fundierte Entscheidungen über Änderungen auch dann getroffen werden können, wenn derjenige, der die ursprüngliche Entscheidung fällte, nicht mehr da ist.

Nyquist schlägt dazu folgende Struktur vor, die hilft, ADR leicht einzuordnen.

Außer den von Nygard vorgeschlagenen ADR-Templates gibt es noch einige andere, auf GitHub gibt es eine Sammlung sowie Verweise auf weitere Quellen. Welches Template für die eigenen Zwecke am Besten geeignet ist, muss jeder für sich entscheiden. Ich empfehle, so einfach wie möglich anzufangen und dann, wenn sich herausstellt, dass bestimmte Informationen fehlen oder überflüssig sind, einen ADR zur Änderung des Templates anzulegen.

Wie gehe ich mit ADR um?

Alle ADR werden fortlaufend nummeriert. Sie haben verschiedene Phasen, die in der Rubrik Status vermerkt werden.

Am Anfang wird ein Problem erkannt, der Kontext analysiert, eine Lösung vorgeschlagen und mit den Nebenwirkungen und Konsequenzen in einem ADR mit Status 'Vorgeschlagen' dokumentiert.

Minimale Korrekturen können im ADR noch eingebracht werden, ansonsten ändert sich nur der Status des ADR, je nachdem ob die Entscheidung angenommen, verworfen oder ersetzt wird.

Eine gute Idee ist es, weitere Konsequenzen zu ergänzen, wenn diese nachträglich bekannt werden. Vielleicht ist es dann jedoch sinnvoll, einen neuen ADR zu schreiben, der die neuen Fakten enthält und den alten ersetzt.

Ich benötige ein Verzeichnis, dass die aktiven ADR zugänglich macht. Bei einer umfangreichen Sammlung kann ich Themenbereiche mit Tags kennzeichnen, um relevante Entscheidungen schneller zu finden. Ersetze ich einen ADR, entferne ich ihn aus dem Verzeichnis und archiviere ihn.

Gibt es ähnliches?

Natürlich sind ADR nichts gänzlich Neues, darum ist ein Blick auf ähnliche Systeme von Vorteil. Weiß ich erst mal, wonach ich suche, finden sich recht schnell weitere Beispiele.

An dieser Stelle möchte ich nur auf zwei Dokumentensammlungen eingehen, die sich in einigen Aspekten mit ADR überschneiden und in anderen von ihnen unterscheiden. Zum einen auf die RFCs der IETF und zum anderen auf Software Entwurfsmuster.

RFC

Requests for Comment sind die Basisdokumente für das Internet. Seit Jahrzehnten fortgeschrieben, enthalten diese Dokumente die grundlegende Beschreibung für die im Internet verwendeten Protokolle und Datenstrukturen.

Dabei werden einmal freigegebene RFC nicht mehr geändert, sondern lediglich durch spätere ergänzt oder ersetzt. Sie haben eine definierte Struktur, die im Laufe der Zeit stärker formalisiert und zum Teil in eigenen RFCs beschrieben wurde. Dabei beschäftigen sich RFCs jeweils mit einem mehr oder weniger komplexen Thema, dass ein bestimmtes Problem lösen soll.

Das sind die Punkte, die RFC mit ADR gemein haben.

Was sie voneinander unterscheidet, ist vor allem der Umfang der RFCs, die sich mit ihrem Thema umfangreich auseinandersetzen, während ADR sich mit einer konkreten Entscheidung befassen und idealerweise auf eine Seite passen.

Ein anderer Punkt ist, dass RFC zwar manchmal den ursprünglichen Kontext und die sich aus der Lösung ergebenden Konsequenzen aufführen, aber nicht notwendigerweise immer.

Außerdem befassen sich RFCs mit allgemeinen Protokollen während ADR sich auf spezifische Probleme in einem konkreten Kontext beziehen, der die Konzentration auf wenige essentielle Dinge erlaubt.

Software-Patterns (Entwurfsmuster)

Entwurfsmuster habem mit ADR gemeinsam, dass sie kurz sind, sich auf genau einen spezifischen Kontext beziehen und die Vor- und Nachteile der Lösung diskutieren. Auch andere Feinheiten der Entwurfsmuster sind interesssant, wenn man sich mit ADR beschäftigen will, führen hier aber zu weit.

Worin sich Entwurfsmuster von ADR unterscheiden, ist vor allem der fehlende Bezug auf konkret auftretende Probleme. Auch benötigen Patterns keinen Status, weil sie nur eine Art Rezept sind, wie man ein bestimmtes Problem lösen kann, wenn es irgendwann auftritt. Andererseits kann ich durch Verweis auf Entwurfsmuster den Text eines ADR erheblich kürzer halten.

Gibt es Hilfsmittel für den Umgang mit ADR?

Nygard selbst verweist in seinem Artikel auf adr-tools, Shellscripts, die automatisch Templates in Markdown anpassen und bei deren Handhabung helfen. Diese haben den Charme, dass die ADR bei Software-Projekten mit im Repository abgelegt werden können und bei GitHub, GitLab und einigen anderen Repositories automatisch formatiert angezeigt werden. Bei anderen Systemen, die Templates erlauben, ist es sinnvoll, einmal Zeit in die Erstellung geeigneter Templates zu investieren.

Referenzen

Posted 2019-02-11
Tags: