Wenn wir in unseren Projekten arbeiten, stehen wir vor der Herausforderung, die Anforderungen unserer Kunden auf irgendeine bestimmte Weise in eine Lösung zu übersetzen. Dabei ist es keine Seltenheit, dass uns am Anfang gar nicht alle benötigten Informationen vorliegen oder sich “unterwegs” Dinge generell noch einmal ändern. Alles, was wir tun, spielt sich also im Kontext von bekanntem und unbekanntem Wissen und Unwissen ab. Vor diesem Hintergrund treffen wir Entscheidungen, die unsere Arbeit entscheidend prägen.
Photo by Tingey Injury Law Firm on Unsplash
Während wir gemeinsam im Team im Projekt unterwegs sind, beteiligen sich alle an den entsprechenden Diskussionen, die zu den Entscheidungen führen. Am Ende eines Meetings wird festgelegt: “So machen wir das jetzt!” Das bedeutet im Einzelnen:
-
So: Wir haben eine Entscheidung getroffen.
-
Machen: Irgendetwas wird sich verändern (oder auch nicht).
-
Wir: Alle waren dabei, alle wissen Bescheid.
-
Das: Genau darum geht es!
-
Jetzt: Genau jetzt gilt, was wir besprochen und diskutiert haben.
Kurz: Wir kennen die Entscheidung, wir setzen sie um und manifestieren sie dadurch. Wir können davon ausgehen, dass sie an irgendeiner Stelle offensichtlich ist, beispielsweise im Quelltext unserer Anwendung. Alles gut.
Alles? Naja, fast. In manchen Fällen wollen wir uns vielleicht noch für die getroffene Entscheidung rechtfertigen und schreiben etwas für die Nachwelt auf.
Für die Nachwelt? Ja, ich hatte es anfangs schon angedeutet: Dinge verändern sich. Ein sehr einfaches Beispiel dafür ist eine Veränderung im Team. Jemand kommt dazu oder verlässt das Team. Beides kann im Hinblick auf unsere getroffene Entscheidung zur Herausforderung werden:
Wer neu dazukommt, kennt die Zusammenhänge noch nicht und die Historie ist nicht ersichtlich. Wer den Anfang verpasst, sieht sich mit einem wie auch immer gearteten Status quo konfrontiert und darf sich darauf einen Reim machen, sieht Entscheidungen umgesetzt, ohne eine Ahnung von der Motivation dahinter zu haben. Alle, die schon einmal abends um 20.45 Uhr den spannenden Blockbuster im Fernsehen eingeschaltet haben, können sicher ohne Weiteres nachvollziehen, dass man hier durchaus ratlos zurückbleiben kann. Zum Glück gibt es noch andere Teammitglieder, die den Anfang nicht verpasst haben und die man um Rat fragen kann.
Moment. Wir erinnern uns: Teamveränderung kann auch bedeuten, dass jemand das Team verlässt. Und mit jedem und jeder, der oder die sich aus dem Team verabschiedet, geht auch ein Stück “historisches” Wissen verloren. Da wir jedoch sehr eng zusammenarbeiten und viel kommunizieren, auch über Projektgrenzen hinweg, ist das kein riesiges Problem. Wir finden schon irgendwie heraus, wer wann am Projekt (und damit an Entscheidungen) beteiligt war, und können nachfragen.
Das ist dann in etwa so, als würde ich dich nach einem Film fragen, von dem ich gehört habe, dass du ihn vor ein paar Jahren mal geschaut hast. Das reicht mir, um dich zu meinem Experten zu machen. Ich werde dich von nun an also mit Details zu jeder beliebigen Szene löchern, die ich nicht so richtig verstanden habe.
Wird das funktionieren? Eher nicht. Es ist viel Zeit vergangen und du hast in der Zwischenzeit jede Menge anderer Filme gesehen. Mit etwas Glück kannst du dich zwar an die entscheidenden Szenen im Film erinnern, doch die für dich entscheidenden Szenen müssen nicht unbedingt die sein, die mir später unklar sind.
Genauso verhält es sich auch in unseren Projekten. Wir verändern unseren Kontext (selbst wenn wir im Projekt bleiben) und Zeit vergeht. Irgendwann können wir uns einfach nicht mehr an jedes Detail, damit verbundene Entscheidungen und die dazugehörigen Beweggründe erinnern.
Mit anderen Worten: Die Nachwelt, für die wir Dinge aufschreiben wollen (sollten), sind wir selbst. Wenn ich heute eine Entscheidung treffe, bin ich gut beraten, sie auch gleich heute (spätestens morgen) für mein Zukunfts-Ich festzuhalten. Und dann kann ich auch genau erklären, warum und mit welchem Wissen, vor welchem Hintergrund sich die Dinge entwickelt haben. Insbesondere dann, wenn sich manche Aspekte noch einmal gravierend ändern, kann es hilfreich sein, sich auf frühere Entscheidungen beziehen zu können.
Welche Informationen sollten wir dafür idealerweise erfassen?
Das ist ein bisschen wie beim Notruf, die Ws sind entscheidend:
-
Wer hat die Entscheidung getroffen?
-
Wann wurde die Entscheidung getroffen?
-
Was ist entschieden worden?
-
Warum war die Entscheidung überhaupt erforderlich?
-
Was hat den Ausschlag für die Entscheidung gegeben?
-
Welche Folgen hat die Entscheidung?
-
Welchen Status hat die Entscheidung?
Das können wir als Minimalset der festzuhaltenden Informationen betrachten. Haben wir all das erfasst, haben wir eine sehr gute Grundlage geschaffen. In manchen Fällen kann es jedoch auch hilfreich sein, noch weitere Informationen zu erfassen:
-
Welche Alternativen wurden in Betracht gezogen?
-
Wo gibt es weiterführende Informationen, wie beispielsweise Aufzeichnungen aus Meetings?
Diese Form der Dokumentation von Entscheidungen ist wesentlicher Bestandteil der Dokumentation von Softwarearchitektur. Beispielsweise sind Architekturentscheidungen im arc42-Template fest vorgesehen (Abschnitt 9 der Dokumentation gibt auch wertvolle Tipps zur Umsetzung und empfiehlt ein Template).
Photo by Maksym Kaharlytskyi on Unsplash
Sehr verbreitet für die Dokumentation von Entscheidungen ist die von Michael Nygard vorgeschlagene Struktur, die sehr klar und einfach ist: Ein “Architecture Decision Record” beantwortet die oben genannten Fragen durch Angaben zu folgenden Punkten:
| Titel | Eine Architekturentscheidung trägt einen prägnanten Titel. Darüber hinaus empfiehlt es sich, die Einträge zu nummerieren. |
|---|---|
| Kontext | Eine Entscheidung wird im Kontext verschiedener Rahmenbedingungen und Anforderungen getroffen, die möglicherweise auch in Widerspruch zueinander stehen können. Dabei geht es nicht allein um technische Fragen oder um die Geschäftslogik. Politische oder soziale Aspekte und Belange des Projekts selbst können ebenfalls eine Rolle spielen. Auch andere Entscheidungen können Teil des Kontexts einer weiteren Entscheidung sein. |
| Entscheidung | Die Entscheidung spiegelt die Reaktion auf die verschiedenen im Kontext beschriebenen Punkte wider. In aktiver Sprache und vollen Sätzen beschreiben wir letztlich wie wir weiterverfahren:
Wir machen das jetzt so. |
| Status | Wenn wir eine Entscheidung treffen, haben wir uns darüber einige Gedanken gemacht. Das bedeutet jedoch nicht gleichzeitig, dass auch alle Stakeholder damit einverstanden sind.
Der Status einer Entscheidung ist also vielleicht zunächst erst einmal “vorgeschlagen” oder sie befindet sich noch im Review, bevor sie “akzeptiert” ist, wenn sich alle Beteiligten darauf geeinigt haben. Mit fortschreitender Zeit und weiteren Veränderungen kann eine Entscheidung aber auch veraltet und überholt, durch eine neue Entscheidung ersetzt sein. Der Status spiegelt das wider (und idealerweise wird auch auf andere verwandte Entscheidungen Bezug genommen). Dadurch ist es uns immer noch möglich, frühere Entscheidungen (und zum Beispiel später verworfene Ideen) nachzuvollziehen. |
| Konsequenzen | Egal, wie die Entscheidung ausfällt – angesichts im Widerspruch zueinander stehender Rahmenbedingungen und Anforderungen können wir davon ausgehen, dass nicht alles “Friede, Freude, Eierkuchen” sein wird. Mit Sicherheit gibt es positive Folgen (sonst hätten wir die Entscheidung ja sicher nicht so getroffen), es kann aber auch Nachteile geben. Eine Entscheidung an einer Stelle zu treffen, kann zum Beispiel bedeuten, an anderer Stelle technische Schulden in Kauf zu nehmen und zu akzeptieren. Andere Konsequenzen sind vielleicht neutral.
Welcher Art eine Konsequenz ist, spielt letztlich keine Rolle, denn alle Konsequenzen spielen eine Rolle: Sie beeinflussen das Team, das Projekt und die Zukunft. Und deswegen gehören sie auch aufgeschrieben. |
Neben dieser Struktur gibt es noch eine ganze Reihe weiterer Vorlagen. Einige hat Joel Parker Henderson in einem GitHub-Repository zusammengestellt, zusammen mit Beispielen und weiteren Hinweisen. Dort finden sich auch Templates, die deutlich mehr Informationen umfassen – und damit potenziell schwieriger zu pflegen sind (auf der anderen Seite aber aussagekräftiger).
Wir stellen fest: Die Entscheidung für oder gegen eine Vorlage für die Dokumentation von Entscheidungen wird auch in einem gewissen Kontext getroffen und ist, natürlich, nicht frei von Konsequenzen. Und haben wir uns für eine Struktur entschieden, stellt sich gleich die nächste Frage: In welchem Format und wo überhaupt wollen wir unsere Entscheidungen dokumentieren? Legen wir unsere Decision Records in einem Git-Repository ab und nutzen die Möglichkeiten der Versionsverwaltung, um Entscheidungen zusammen mit dem Code zu versionieren, so dass wir auf den ersten Blick immer die jeweils aktuellen und gültigen Entscheidungen sehen, aber trotzdem in der Historie zurückschauen können? Entscheiden wir uns stattdessen für idempotente Dokumentation von Entscheidungen, d.h., eine einmal getroffene und dokumentierte Entscheidung bleibt in dieser Form bestehen und wird nicht mehr verändert, höchstens durch eine neue Entscheidung abgelöst? Soll es Housekeeping-Regeln geben, nach denen längst überholte Entscheidungen doch irgendwann gelöscht oder zumindest archiviert werden, um die Dokumentation übersichtlicher zu gestalten? Und, was ist eigentlich eine Entscheidung, die mit einem Architecture Decision Record festgehalten werden muss?
Wir haben uns für einen eher pragmatischen Ansatz entschieden:
-
Die von Michael Nyberg vorgeschlagene Struktur dient als Ausgangspunkt. Wir haben zusätzlich das Datum, Entscheider und Themen oder Schlagwörter ergänzt. Außerdem werden unsere Entscheidungen in grobe Kategorien eingeteilt. Werden es irgendwann zu viele, könnten wir unser Decision Log so beispielsweise separieren.
-
Jede Entscheidung wird auf einer eigenen Seite in unserem Wiki festgehalten und die Entscheidungen selbst werden zusätzlich zusammen mit Status und Datum in einer Übersicht dargestellt.
-
Sehen wir für einzelne Entscheidungen die Notwendigkeit weiterer Informationen, werden sie einfach auf der Wiki-Seite unter den Punkten der Grundstruktur ergänzt. Das können Pro- und Contra-Tabellen zu verschiedenen Alternativen, Diskussionsnotizen, ausführlichere Konzeptbeschreibungen oder auch einfach nur Links zu Meeting-Notizen sein. Was auch immer in Zusammenhang mit einer Entscheidung von Bedeutung sein kann, wird auch dort festgehalten.
Mit dieser Struktur fahren wir jetzt bereits eine ganze Weile ziemlich gut. Partner, die neu ins Projekt gekommen sind, konnten sich auf Basis der so festgehaltenen Historie einen guten Überblick verschaffen und schnell in fachliche oder technische Diskussionen mit fundierten Beiträgen einsteigen.
Photo by John Schnobrich on Unsplash
Überhaupt diskutieren wir gern, und die Frage “Brauchen wir dazu ein Decision Record?” ist schon in Fleisch und Blut übergegangen. In den meisten Fällen lautet die Antwort dann “Ja!”
Aber gibt es eine Faustregel, was als Entscheidung dokumentiert werden muss und was nicht? Im Artikel “Gut dokumentiert: Architecture Decision Records“ bei heise online heißt es dazu:
“Gute Anzeichen für die Notwendigkeit der Dokumentation ist, wenn eine Entscheidung von bestehenden Best Practices oder eigenen Standards abweicht oder ihr lange Diskussionen vorausgegangen sind.”
Das können wir bestätigen: In der Anfangszeit war es vielleicht noch so, dass wir manches zwar besprochen, uns auch geeinigt hatten, das aber nicht gleich aufgeschrieben haben. Das Ergebnis war dann, dass wir später wieder die gleiche oder eine ähnliche Diskussion (mit vielleicht neuem Kontext) geführt haben. Das waren Momente zum Innehalten, zum Reflektieren der Entscheidung – und zum Dokumentieren.
Wir machen das jetzt. So!