Kurzdefinition

Kurzes Dokument, das eine Entscheidung zur Softwarearchitektur festhält: den Kontext, der sie nötig machte, die erwogenen Optionen, die gewählte Option und die akzeptierten Konsequenzen. Abgekürzt ADR.

Ausführliche Definition

Die Praxis stammt aus den Entwicklungsteams und ist dort weithin etabliert. Ihr Sinn ist zeitlich: Mehrere Monate oder Jahre später muss jemand, der nicht dabei war, verstehen können, warum eine technische Wahl getroffen wurde — warum eine Warteschlange eingeführt wurde, um bestimmte Nachrichten asynchron zu verarbeiten, welche Optionen verworfen wurden, was die Wahl ermöglicht und was sie einschränkt.

In den Artikeln dieses Blogs dient der Begriff als Herkunftsreferenz und nicht als Gegenstand für sich: Er hilft, den Product Decision Record einzuordnen, der die Struktur übernimmt und den Gegenstand von der technischen Komponente auf die Produktregel verschiebt. Der Unterschied im Wesen liegt in dem, was festgehalten wird — ein ADR legt eine Entscheidung darüber fest, wie das System gebaut wird, ein PDR eine Regel, die auf künftige Situationen anwendbar ist.

Der ADR hat eine Eigenschaft, die das Produktvokabular schlecht übernimmt: Er dokumentiert üblicherweise Vorhaben ohne sichtbaren Geschäftswert. Ein Monat Arbeit an einer Warteschlangen-Technologie liefert dem Endnutzer nichts und kann doch einen Engpass beseitigen, durch bloßes Hinzufügen von Servern das Zehn- bis Dreißigfache der Last bewältigen und den Verkauf zusätzlicher Kundenkonten möglich machen.

Gebrauch im Feld

Der Begriff taucht in Diskussionen über das technische Gedächtnis eines Teams auf, über die Rechtfertigung von Vorhaben ohne funktionale Auslieferung, und als Vergleichspunkt, sobald man ein gleichwertiges Instrument auf der Produktseite vorschlägt.

Synonyme und Varianten

„Architekturentscheidung“, „ADR“, „Architektur-Log“. Der Plural „die ADRs“ bezeichnet im Sprachgebrauch ebenso das ganze Register wie seine Einträge.

Nicht zu verwechseln mit

• Product Decision Record — Product Decision Record — dieselbe Dokumentform, angewendet auf eine übergreifende Regel für Produktentscheidungen; sie legt keine Entscheidung darüber fest, wie gebaut wird.
• Architekturdokumentation — Beschreibung des Systems, wie es ist; der ADR beschreibt einen Moment der Entscheidung und wird nicht aktualisiert, wenn sich das System weiterentwickelt.
• Technische Spezifikation — Beschreibung dessen, was umzusetzen ist und wie; sie folgt aus einer Architekturentscheidung, rechtfertigt sie aber nicht.

Beispiele

„Eine Anwendung erfährt einen Lastanstieg. […] Das Team entscheidet sich dann, eine Warteschlangen-Technologie einzuführen, um bestimmte Nachrichten asynchron zu verarbeiten.“ — die typische Situation, die der ADR festhält.

„Warum wurde sie getroffen? Welche Optionen wurden verworfen? Welche Konsequenzen werden akzeptiert? Was ermöglicht sie? Was schränkt sie ein?“ — die Fragen, die der Eintrag beantwortet.

Mehrdeutigkeiten / Debatten

Der übliche Sprachgebrauch schwankt bei der Unveränderlichkeit: Manche Teams führen ihre ADRs als eingefrorene Dokumente und kennzeichnen Ersetzungen, andere aktualisieren sie wie eine lebende Dokumentation. Der hier verwendete Sinn folgt der ersten Praxis, die auch der PDR übernimmt.