Softwarearchitekturen dokumentieren und kommunizieren

Folge 8: Für die Ewigkeit? Die Tonne? Oder etwas dazwischen?

Logo Kolumne
Mein Vater hat unlängst die ursprünglich auf Zelluloid gebannten Kindheitserinnerungen seiner Sprösslinge („Stefan lernt laufen“ etc.) auf DVD gesichert. Vor ein paar Jahren hatte er bereits die original Super 8-Stummfilme mit einer Videokamera von einer Leinwand abgefilmt. Die VHS-Bänder dienten nun als Quelle für die DVD. Technologie veraltet; wer Dokumentiertes dauerhaft bewahren will, muss sich damit auseinander setzen, dass auch zukünftige Interessierte die Sachen verwenden können.

Drohen Ihrer Architekturdokumentation ebenfalls technische Umwälzungen? Architektur entsteht zu großen Teilen früh im Projekt. Die Dokumentation dazu beginnt im Idealfall gleichzeitig, die Ergebnisse (Sichten, Modelle, dokumentierte Entscheidungen) begleiten die Softwarelösung vom Laufen lernen durch die Entwicklungsiterationen bis in Betrieb und Wartung hinein. Auch sie sind der Gefahr ausgesetzt, irgendwann nicht mehr verwendet werden zu können. Aber das kann sehr unterschiedliche Ursachen haben – selten technische.

Variante 1: „Nicht mehr aufzufinden“. Beispiel: Architektur wird im Rahmen von gemeinsamen Designmeetings und –workshops entworfen, die Ergebnissicherung in Form von Fotoprotokollen (Flipcharts, Whiteboards) oder direkt erstellten Dateien erfolgt aber nicht nachhaltig. „Wo ist eigentlich die tolle Graphik, die wir Anfang des Monats mit diesem Mindmapping-Werkzeug gemeinsam am Beamer erstellt haben?“ – „Ich glaube, die hatte Uwe lokal auf seinem Notebook gespeichert.“
 
Variante 2: „Nicht mehr zu entziffern“. Schon viele Ergebnisse wurden nicht weiterverwendet, weil die Tools, mit denen sie ursprünglich erstellt wurden, nicht mehr, oder zumindest nicht in der geforderten Version zur Verfügung standen. „Ich würde gern UML-Diagramme in der Dokumentation aktualisieren. Mit was für einem Tool sind die gemalt worden? Die Dateiendung kenne ich gar nicht.“ – „Da hatten wir damals ’ne Eval von.“

Physische Verlustrisiken sind beherrschbar. Und bei der Wahl der verwendeten Werkzeuge wird in der Regel auch weiter geschaut als 30 Tage. Die interessanteste Ursache ist Variante 3: „Nicht mehr aktuell“. Neue Teammitglieder stoßen bei der Einarbeitung gern auf solche Artefakte. „Ich habe eine Frage zu Eurem Dokument hier: Die dargestellte Zerlegung finde ich in der aktuellen Software so überhaupt nicht wieder.“ – „Wo hast Du das denn ausgegraben? Das pflegen wir seit der Völkerwanderung nicht mehr!“.

Wie können Sie Ihre Architekturdokumentation vor diesem Effekt schützen? Weniger ist oft mehr. Konzentrieren Sie sich auf das Wesentliche, und wählen Sie auch bewusst Sichten auf Ihre Lösung aus, die Sie berechtigt weglassen, bzw. schlank halten können.

Weiterhin hat eine gute Dokumentation wenn man mag selbst eine Architektur. Das Entwurfsprinzip, Stabiles von Instabilem zu trennen, lässt sich auch auf die Strukturierung von Architekturdokumentation wunderbar anwenden. Es kann helfen, Pflegeaufwände zu reduzieren. Auch das Zusammenspiel von Stabilität und Abstraktion kann positive Wirkung entfalten. Wenn Sie in bestimmten Teilen Stabilität anstreben, dokumentieren Sie Abstraktionen, nicht Entwürfe auf gleichem Detaillierungsgrad wie der Quelltext.
 
Es ist nichts Falsches daran zu entscheiden, Teile der Architekturdokumentation im Verlauf des Projektes nicht mehr zu aktualisieren, wenn der Pflegeaufwand in keinem Verhältnis mehr zum Nutzen steht. Nur sollte dies dann klar im Team kommuniziert und die Teile als solche gekennzeichnet werden, z.B. als „historisches Zeugnis“. Als attraktivere Alternative dazu ist jetzt vielleicht der Zeitpunkt gekommen, Details wegzulassen, statt sie immer wieder anzupassen, die Dokumentation so zu verdichten, und auf Abstraktionen zu reduzieren. Um auf diese Weise zu Prägnanz und Stabilität zu kommen.

Mein Vater hatte bei seinen Überspielungen nicht alle Super 8-Filme auf Video übernommen, und auch nicht alle VHS-Bänder auf DVD überführt. Er hat ausgewählt und ausgeklammert, und für den Empfänger der Dokumentation (mich) so einen Mehrwert geschaffen. Das Ergebnis ist leichter zu konsumieren und präsentieren, und erfüllt damit seinen Zweck.
JavaMagazin 05.2009
Zuerst erschienen hier:
Stefan Zörner: Kolumne Architekturen dokumentieren.
"Für die Ewigkeit? Die Tonne? Oder etwas dazwischen?", Java Magazin, 05/2009, 1 Seite, S. 83
(mit freundlicher Genehmigung)