Stefan Zörner
02.10.2016
Vermeide Mehrdeutigkeit. Erkläre Deine Notation. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit. Im dritten und letzten Teil dieser kleinen Blog-Serie ("Tafel 3") diskutiere ich die verbleibenden Regeln für gute (Architektur-)Dokumentation im heutigen Licht. Der Quelltext erzählt nicht die ganze Geschichte.
In den zwei vorherigen Beiträgen hatte ich bereits mit der kurzen Diskussion der klassischen sieben Regeln für gute Dokumentation begonnen. Ich schließe sie in diesem Beitrag mit den beiden verbleibenden Regeln 3 und 7 ab.
Hier noch einmal kurz zur Erinnerung alle sieben im Überblick:
| 1. Schreibe aus Sicht des Lesers. | (Tafel 1) |
| 2. Vermeide unnötige Wiederholungen. | (Tafel 2) |
| 3. Vermeide Mehrdeutigkeit. Erkläre Deine Notation. | (Tafel 3) |
| 4. Verwende eine Standardstrukturierung. | (Tafel 2) |
| 5. Halte Begründungen für Entscheidungen fest. | (Tafel 1) |
| 6. Halte Dokumentation aktuell, aber auch nicht zu aktuell. | (Tafel 2) |
| 7. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit. | (Tafel 3) |
Es ist unstrittig, dass sich bestimmte Informationen mit Bildern besser kommunizieren lassen als mit Text allein. Das gilt für Strukturen (Elemente und deren Beziehungen untereinander) ebenso wie für Abläufe (Folgen von Aktionen mit Alternativen, Wiederholungen, Parallelität). Ab einer gewissen Komplexität lässt sich das mit Stichpunkten oder Prosa nicht gut beschreiben. Diagramme und mitunter auch Screenshots kommen ins Spiel, bei Diagrammen ist in der Softwarearchitektur immer noch UML recht verbreitet.
In diesem Zusammenhang höre ich in Projekten oft: “Wir benutzen für unsere Architekturdiagramme UML. Die Notation ist standardisiert. Kann jeder lesen.” Das mit dem standardisiert stimmt, meine Erfahrungen mit “kann jeder lesen” sind andere.
In der Projektpraxis werden übrigens oft gar keine Architekturdiagramme angefertigt. Auch weil die Teammitglieder unsicher in der Notation sind. Sie glauben sie müssten UML nehmen aber haben Angst sich damit zu blamieren. Aus meiner Sicht ist UML zu verwenden kein Automatismus, und bei den vielen Zielgruppen (vgl. Regel 1) wird auch bei der UML Erklärungsbedarf da sein.
In diesem Zusammenhang zwei persönliche Ratschläge von mir rund um Diagramme:
Der erste Tipp sorgt zum einen dazu, dass Betrachter nicht rätseln müssen, was Ihr mit dem Bild sagen wollt. Zum anderen (und das ist das Entscheidende) hilft es Euch zu entscheiden, ob etwas “noch ins Bild reingehört” oder nicht. Ihr vermeidet Diagramme voller Prachtfülle, in denen der Leser die relevanten Informationen dann aber suchen muss wie in einem Wimmelbild. Hier ein schönes Fundstück aus dem Netz dazu (Quelle, beachtet die beschönigende Überschrift).
Immerhin: Eine Legende hat dieses Diagramm. Die Regel “Erkläre Deine Notation” wende ich durchaus auch auf UML an. Und wenn Ihr dort wenige Elemente verwendet braucht Ihr auch nur wenig erklären. Die wenigen UML-Elemente dann aber bitte richtig verwenden. Sonst verwirrt Ihr diejenigen, die UML lesen können (gibt es auch).
Hinter dieser Regel stecken Reviews, zumindest suggeriert das Wort “überprüfen” das. Dokumentation kann man auf zwei Arten überprüfen. Die erste nenne ich gern “Überprüfung auf Standardkonformität”. Hier werden Kriterien an die Dokumentation gelegt und Fragen folgender Art gestellt (Beispiele):
Fragen dieser Art eignen sich prima für Checklisten, diese können in der Regel von einer QS-Abteilung abgearbeitet werden. Mitunter erfordern regulative Randbedingungen einen solchen Check auf Standardkonformität. Mit der Überprüfung auf Gebrauchstauglichkeit ist aber etwas anderes gemeint.
Nämlich dass die Dokumentation tatsächlich bei der Arbeit unterstützt. Diejenigen, welche Architektur kommunizieren wollen, und diejenigen, welche sich dafür interessieren. Also für Architekturtreiber, Lösungsansätze, Entscheidungen, Konzepte. Die geschlossenen Fragen von oben können das nicht leisten.
Die Überprüfung auf Gebrauchstauglichkeit findet als Test mit den Zielgruppen statt. Und hier schließt sich der Kreis von Regel 7 zu Regel 1 (“Schreibe aus Sicht des Lesers”). Das Anfertigen eines Architekturüberblicks stelle ich überhaupt gerne als Kreislauf dar (initial klein Starten, dann schrittweise Verfeinern). Eine Darstellung dieser Idee findet Ihr zum Beispiel in unseren Architektur-Spicker #1 (“Der Architekturüberblick”, Download als PDF auf Seite 3 oben.
Architekturikonen in Software. Wegweisende Lösungen im Porträt
Serie arc42-Starschnitt – Ein Architekturüberblick in Lebensgröße
Blog-Beitrag: Ist dieses arc42 eigentlich alternativlos?