Frank PientkaInnovation und Technologie

Dokumentation ist wichtig!

Eine gute und aktuelle Architekturdokumentation ist ein gutes Kommunikationsmittel, um insbesondere Architekturentscheidungen und Qualitätsmerkmale aus unterschiedlichen Sichtweisen zu betrachten und zu überprüfen. Was tun, wenn die Zeit für Dokumentation fehlt oder Dokumentation nicht die notwendige Priorität hat? Hier hilft die Architekturvorlage ARC42.

Gut ist es, wenn die Dokumentation Fragen nach dem warum, was, wie und wohin in ausreichender Form behandelt werden. Besonders wichtig es ist, den Problem- und damit Lösungsraum möglichst früh ab- und eingrenzen. Um nicht jedes Mal das Rad neu zu erfinden oder in der Projekthektik wichtige Fragen unbeantwortet zu haben, sind Vorlagen hilfreich. Eine typische Vorlage vom groben über das kleine zum zukünftigen könnte wie folgt aussehen. Der Lösungsteil hat meist den größeren Umfang und wächst mit der Zeit.

  1. Aufgabenstellung: Was?
  2. Überblick: Was? Wie?
  3. Die Lösung im Detail: Wie? Warum?
  4. Fazit und Ausblick: Wohin noch?

Die beliebte Architekturvorlage ist ARC42 und hat folgende Struktur:

  1. Einführung und Ziele
  2. Randbedingungen
  3. Kontextabgrenzung
  4. Lösungsstrategie
  5. Bausteinsicht
  6. Laufzeitsicht
  7. Verteilungssicht
  8. Konzepte
  9. Entwurfsentscheidungen
  10. Qualitätsszenarien
  11. Risiken
  12. Glossar

ARC42 ist ein Schrank mit zwölf Schubladen. Dabei hängt es vom Anwendungsfall und Vorgehen ab, wie voll die einzelnen Schubladen sind. Oftmals befindet sich nur ein kleiner Notizzettel darin. Wichtig ist es, den Schrank regelmäßig auszumisten, damit nur die aktuell benötigten Informationen dort enthalten sind. Die zwölf Schubladen lassen sich in vier Hauptkategorien einteilen:

  • Anforderungen (Kapitel 1, 2, 3, 10, 12)
  • Strukturen (Kapitel 5, 6, 7)
  • Konzepte (Kapitel 4, 8)
  • Entwurfsentscheidungen (Kapitel 9, 11)

Im Vorfeld sind noch einige organisatorische, aber auch technische Fragen zur Dokumenterstellung und -pflege zu beantworten. Soll das Dokument beispielsweise nur von bestimmten Rollen oder vom ganzen Team gepflegt werden. Welche Dokumentformate eingesetzt werden, hängt auch vom Leserkreis ab. Oftmals ist es eine Mischung aus grafischen Visualisierungswerkzeugen, wie zum Beispiel Visio, Gliffy und Whiteboard-Fotos, und anderen Werkzeugen wie Word, Wiki, Asciidoc und PowerPoint.

Bei den jeweils geeigneten Dokumentationsarten stellen sich die Fragen: Malen, schreiben oder basteln? Das Problem mit Bildern ist, dass nicht alle gleich aussagekräftig sind. Deswegen sollte eine Legende und konsistente Darstellung auch für Farben und Symbole verwendet werden. Am besten werden Notationen erklärt.

Manche vertreten den Standpunkt, dass die eigentliche Wahrheit im Code und nicht im Architekturdokument ist. Der Quelltext erzählt jedoch nicht die ganze Geschichte. Es fehlt oft eine hilfreiche Abstraktion und beantwortet nicht die Fragen nach Qualitätsmerkmalen und getroffenen Entscheidungen. Da Entscheidungen nicht transparent gemacht oder abgestimmt werden, werden auch deren Wechselwirkungen wenig betrachtet. Dies kann zu technischen „Schulden“ führen, die oftmals zu spät erkannt und dann kaum systematisch angegangen werden.

Das Prinzip aus dem agilen Manifest „Funktionierende Software ist wichtiger als umfassende Dokumentation“ bedeutet eben nicht, dass auf Dokumentation verzichtet werden kann. Mit dem rechten Maß ist eine aktuelle, zielgruppenorientierte und bedarfsgerechte Dokumentation mindestens genauso wertvoll wie der Code. Es wäre schade, wenn eine Architekturdokumentation zur Schrankware verkommt und veraltet oder kaum gelesen wird. Deswegen ist es wichtig, dass bestimmte Rollen (Redaktionskreis) verantwortlich sind und es regelmäßig aktualisiert und überprüft wird. Gerade Teamneulinge können hier gute und kritische Leser sein. Letztlich muss aber das gesamte Team über diese zentrale Dokumentation informiert sein.

Über sieben Brücken sollte eine gute Architekturdokumentation gehen, um mit einer einheitlichen Struktur den Lesern und Entscheidern in einer klaren und transparenten Form wichtige aktuelle Information zu liefern. Wie beim Kochen müssen bei der Dokumentation die Zutaten durch handwerkliches Können und Wissen zu einem schmackhaften Gericht immer wieder frisch erstellt werden. Jede gute Architekturdokumentation ist Arbeit, die sich lohnt. Auch hier machen nur eine regelmäßige Übung, zeitnahe Aktualisierungen und permanentes Lernen einen Meister.

Schlagwörter: ,