Aktionen

Architekturentscheidungen dokumentieren

Aus PQWiki


SE-Disziplin

Schnelligkeit
★★★
Einfachheit
★★★
Agilität
★★★

Ziele

* Wichtige Architekturentscheidungen festhalten und archivieren
  • Inkonsistenzen im System vermeiden
  • Wiederholte Diskussionen und Änderungsänderungen vermeiden
  • Neue Mitarbeiter schnell einarbeiten

Motivation/Problemstellung

Das Manifest für agile Softwareentwicklung stellt den Wert funktionierender Software über den einer umfassenden Dokumentation. Dies wird in agilen Entwicklungsprojekten häufig falsch uminterpretiert zu „es soll keine Dokumentation erstellt werden“. Aus diesem Grund, gepaart mit hohem Projekt- und Featuredruck, ist die Dokumentation der Architektur eines Systems häufig eine der ersten Aktivitäten, auf die verzichtet wird. In der Tat ist Dokumentation eine Investition, die keinen unmittelbaren Kundennutzen erzielt. Trotzdem führt der der vollständige Verzicht in der Regel zu einigen negativen Konsequenzen: Werden insbesondere schwierige Design-Entscheidungen nicht dokumentiert, werden diese häufig in unregelmäßigen Abständen wiederholt in Zweifel gezogen und neu diskutiert, weil die Begründungen und Abwägungen in Vergessenheit geraten. Es ist häufig schon nach kurzer Zeit nicht mehr klar, warum eine Entscheidung getroffen wurde. Das Fehlen der Dokumentation von Entscheidungen kann außerdem zur inkonsistenten Umsetzung von beschlossenen Konzepten führen, da die gemeinsam getroffenen Entscheidungen den Team-Mitgliedern nicht mehr präsent sind oder unterschiedlich interpretiert werden. Dies ist insbesondere bei querschnittlichen Konzepten der Fall, die mehrfach instanziiert werden. Solche Uneinheitlichkeiten führen zu einer eingeschränkten Wartbarkeit oder erhöhten Korrekturaufwänden. Außerdem macht ein vollständiges Fehlen von Dokumentation die Einarbeitung neuer Mitarbeiter mühsam und zeitaufwändig.

Kurzbeschreibung

Dokumentation Architekturentscheidung.png
Mit der Aufnahme von Dokumentation in die Definition of Done und der Bestimmung eines Verantwortlichen für Dokumentation kann eine Zunahme von Dokumentation im Projekt erreicht werden. Das gesamte Team erstellt Dokumentation, indem nach einer Konzeptentwicklung die wichtigsten Entscheidungen, Whiteboarddiagramme und einige Stichpunkte als Erklärung festgehalten werden. Abgelegt werden die Informationen bei der jeweiligen Aufgabe in dem Taskmanagement-Werkzeug mit dem das Team ohnehin bereits arbeitet. Optimalerweise wird dies direkt nach der Erarbeitung eines Konzepts, spätestens aber vor dem Iterationsende erledigt.

Input

* Architekturkonzepte und -entscheidungen

Output

* Leichtgewichtige Dokumentation

Rahmenbedingungen

Rolle (Ausführender)

Dokumentationsverantwortlicher, Gesamtes Team

Werkzeuge, Hilfsmittel

Whiteboard, Taskmanagement-Werkzeug

Vorkenntnisse und Erfahrungen

-

Ort und Umgebung

Büro

Weitere Teilnehmer

-

Voraussichtliche Dauer

Ca. 15 Minuten pro Dokumentation

Vorgehensweise

Vorbereitung

Um ein Mindestmaß an Dokumentation zu erreichen, kann die Voraussetzung „Dokumentation erstellt“ in die Definition of Done aufgenommen werden. Das heißt, eine Aufgabe gilt erst dann als erledigt, wenn die entsprechende Dokumentation erstellt wurde. Außerdem kann es sinnvoll sein, ein Teammitglied als Dokumentationsverantwortlichen zu benennen. Dieser hat nicht die Aufgabe, sämtliche Dokumentationen zu erstellen, soll aber im Team darauf zu achten, dass die Definition of Done bezüglich Dokumentation eingehalten wird und bei Bedarf andere Entwickler auf das Fehlen hinzuweisen. Im Fall von Scrum eignet sich dafür der Scrum Master. Für die Erstellung der Dokumentation ist das gesamte Team verantwortlich.

Durchführung


Um den Aufwand zu begrenzen, sollte die Dokumentation leichtgewichtig gestaltet werden. Oftmals genügen einige wenige Sätze um getroffene Architekturentscheidungen ausreichend zu erklären. Werden Architekturkonzepte gemeinsam im Team entwickelt, sollten die getroffenen Entscheidungen genannt und erläutert werden. In jedem Fall sollte neben der eigentlichen Nennung und Erklärung die Begründung dokumentiert werden, warum das Team eine bestimmte Entscheidung gewählt hat. Dies umfasst vor allem auch verworfene Alternativen. Im Team werden häufig gemeinsam Diagramme am Whiteboard erstellt. Diese Diagramme sollten abfotografiert und mit einigen wenigen Stichpunkten zur jeweiligen Dokumentation hinzugefügt werden. Darüber hinaus können optional noch Auswirkungen auf andere Entscheidungen beschrieben werden. Um die Dokumentation abzulegen ist die Einführung eines zusätzlichen Werkzeugs in den meisten Fällen wenig erfolgsversprechend. Diese werden gewöhnlich nicht verwendet. Daher bietet sich die Nutzung bereits vorhandener Werkzeuge an. Agile Teams arbeiten meist mit Aufgabenverwaltungssystemen, wie virtuellen Scrum Boards. In solche Werkzeuge lassen sich leichtgewichtige Dokumentationen, bestehend aus wenigen Erklärungen und Fotos meist gut integrieren. Dazu wird die Dokumentation an die entsprechenden Aufgaben angehängt. Der primäre Vorteil dabei ist, dass die Hürde zur Erstellung der Dokumentation sehr gering gehalten wird, da die Entwickler ohnehin mit diesem Werkzeug arbeiten. Allerdings ergibt sich dadurch eine Dokumentation, die über viele Stories verteilt und damit nur schwer zusammenhängend zu lesen ist. Außerdem wird eine solche Dokumentation nachträglich in nur in wenigen Fällen noch einmal angepasst. Bezüglich des Dokumentationsmediums und der Ablage ist also eine Abwägung zu treffen.

Nachbereitung

Eine solche Dokumentation sollte von allen Teammitgliedern, idealerweise gleich während oder direkt nach der Konzepterarbeitung und dem Treffen der Entscheidungen erstellt werden. Zu diesem Zeitpunkt können noch die meisten Informationen und Details aus der Erinnerung abgerufen werden. Spätestens aber müssen die Informationen kurz vor Ende der Iteration aufgeschrieben worden sein. Ist die Dokumentation ein Teil der Definition of Done, ist die Aufgabe nicht vollständig erledigt, wenn die Dokumentation noch fehlt.

Gütekriterien/Empfehlungen

Für diese Best Practice ist es essentiell, dass nicht nur die Designentscheidungen selbst, sondern auch die Begründungen aufgenommen werden. Nur so lassen sich die beschriebenen wiederholten Diskussionen vermeiden und Entscheidungen auf einer fundierten Basis neu bewertet werden. Um die Wahrscheinlichkeit zu erhöhen, dass sich alle Entwickler an der Erstellung der Dokumentation beteiligen, muss einerseits die Hürde durch Werkzeuge so niedrig wie möglich gestaltet werden, andererseits die Forderung nach Dokumentation konsequent aufrecht erhalten werden.

Risiken

Wird diese Best Practice neu eingesetzt, sollte darauf geachtet werden, dass der Umfang und der Aufwand für Dokumentation begrenzt bleibt. Es sollten nur die wichtigsten Entscheidungen und Informationen in Stichpunkten und einfachen Diagrammen festgehalten werden. Ansonsten besteht die Gefahr, dass Dokumentation erneut als Ablenkung von den eigentlichen Aufgaben ohne Mehrwert empfunden wird.

Einordnung in das PQ4Agile-Qualitätsmodell

Schlagworte

Architektur, Dokumentation, Entscheidungen

Weiterführende Informationen

Informationen im Internet

Literatur

Zörner, Stefan. Softwarearchitekturen – Dokumentieren und Kommunizieren. Carl Hanser Verlag München. ISBN 978-3-446-42924-6. 2012