Die sieben Regeln für gute Dokumentation in Stein gemeißelt? (2/3)

In einem früheren Beitrag (“Tafel 1”) hatte ich bereits mit der kurzen Diskussion von zwei der sieben Regeln für gute Dokumentation begonnen.

Hier geht es weiter. Nochmal kurz zur Erinnerung alle Regeln im Überblick:

1. Schreibe aus Sicht des Lesers.	(Tafel 1)
2. Vermeide unnötige Wiederholungen.	(Tafel 2)
3. Vermeide Mehrdeutigkeit. Erkläre Deine Notation.
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.

Starten möchte ich mit einer Regel die falsch angewendet sogar richtig Schaden anrichten kann. Der vierten.

Verwende eine Standardstrukturierung (Regel 4)

Wenn Ihr Dokumentationszutaten über den Quelltext hinaus anfertigt (beispielsweise Schritt-für-Schritt-Anleitungen zu übergreifenden Themen wie Persistenz oder Security) stellt sich die Frage wo Ihr das Ganze ablegt und strukturiert. Diese vierte Regel wird gerne als Reklamesatz für arc42 herangezogen. arc42 stellt eine Standardgliederung für Architekturbeschreibungen dar (in D-A-CH De-facto-Standard).

Tatsächlich findet alles irgendwie seinen Platz in arc42 (der Abschnitt “Konzepte” entpuppt sich dabei in der Praxis als Joker). Ich rate Euch aber davon ab, Architekturdokumentation initial anzufertigen, in dem Ihr eine vollständige arc42-Gliederung (immerhin 12 Abschnitte) geschlossen z.B. als Word-Dokument “ausfüllt”.

Den Wert von arc42 sehe ich vor allem im Nennen möglicher Zutaten einer Dokumentation, die zusätzlich zum Quelltext im Team entstehen. Die Kontextabgrenzung etwa, oder Qualitätsziele. Hier gibt es übrigens große Überdeckungen zu Alternativen. Die arc42-Gliederung selbst hat dann ihren großen Auftritt, wenn Ihr eine Architekturbeschreibung aus den einzelnen Bestandteilen für eine bestimmte Zielgruppe zusammen setzt. Darüber hinaus hilft die Struktur auch beim Verwalten der Teile.

Standardgliederungen funktionieren übrigens auch in kleinerem Rahmen gut. Muss nicht gleich die ganze Architekturbeschreibung sein. Beispielsweise bei Schnittstellen und Entscheidungen ist die immer gleiche Struktur hilfreich. Sie gibt den Erstellern Sicherheit und Orientierung. Im Falle von Architekturentscheidungen unterstützt sie auch das Treffen derselben (die Dokumentation fällt ab). Dieser Beitrag enthält eine praxisbewährte Gliederung für Architekturentscheidungen.

Der Schaden, den diese vierte Regel nun anrichten kann, entfaltet sich in Kombination mit der nächsten.

Vermeide unnötige Wiederholungen (Regel 2)

Beim Nachdenken über diese Regel stolpere ich über das Wort “unnötig”. “Don’t repeat yourself” ist ein prominentes Prinzip (auch DRY). Wenn hier explizit von “unnötigen” Wiederholungen die Rede ist, scheint es auch solche zu geben, die nötig oder zumindest OK sind. DRY gibt mehr Orientierung … Was will und Regel 4 sagen?

Falls Ihr Architekturdokumentation wie oft gesehen in einem arc42-Dokument in Word anfertigt, geratet Ihr bei Anwendung von “Schreibe aus Sicht des Lesers” (Regel 1) in ein Problem: Ein einziges Dokument  wird mehrere Zielgruppen nicht gerecht. Widersteht dem Reflex, einzelne Dokumente für die jeweiligen Zielgruppen anzufertigen (gute Idee eigentlich), und die betreffenden Inhalte dann jeweils hinein zu kopieren (schlechte Idee). Ihr lauft Gefahr, dass sich die geklonten Inhalte unabhängig voneinander ändern, und/oder habt hohe Wartungsaufwende.

Fertigt die Inhalte stattdessen jeweils einmal kleinteilig an, und führt sie bei Bedarf in unterschiedlichen  Dokumenten oder anderen Formen zusammen. Am besten geht dies automatisiert, etwa im Rahmen des Build-Prozesses. In der Projektpraxis sehen wir als Formate hier eher Markdown oder (häufiger) AsciiDoc als Word. Diese fühlen sich in einer Versionsverwaltung wohl; diff und merge funktionieren prima. Mit Hilfe von Includes entstehen passende Dokumente für unterschiedliche Zielgruppen durch Rekombinieren der Inhalte. Dieser Beitrag stellt eine entsprechende Werkzeugkette mit Markdown und Maven bzw. alternativ Gradle vor.

Ebenso wie einzelne Architekturdokumentation für unterschiedliche Zielgruppen durch Cut/Copy/Paste zu erzeugen solltet Ihr keine umfangreichen Inhalte aus anderen Teilen der Dokumentation (Klassiker: Anforderungen) in Eure Dokumentation kopieren. Verweist auf sie. OK ist aus meiner Sicht eine knappe Zusammenfassung, um den Lesern das Verfolgen des Links zu ersparen, die nur einen Überblick haben wollen. Hier handelt es sich um einen Kompromiss zwischen leichter Lesbarkeit und Wartbarkeit. Das führt zu Wiederholungen, die im Sinne der Regel OK sind.

Halte Dokumentation aktuell, aber auch nicht zu aktuell (Regel 6)

Veraltete Dokumentation ist häufig eine Ausrede um überhaupt nicht zu dokumentieren. Dahinter stecken zwei Annahmen:

1. Dokumentation veraltet sowieso
2. Veraltete Dokumentation ist wertlos

Dazu lässt sich sagen: Eine festgehaltene (Architektur-)Entscheidung veraltet keineswegs, solange Ihr nicht von ihr abweicht. Vielleicht würdet Ihr heute anders entscheiden, mittlerweile haben sich Rahmenbedingungen oder Ziele geändert, Optionen sind dazugekommen, Annahmen haben sich als falsch herausgestellt. Kurz: Ihr seid schlauer.

Um die Entscheidung nachvollziehen zu können ist aber der Zeitpunkt der Entscheidung relevant. Und da Architekturentscheidungen typischerweise schwer zurückzunehmen sind, ist eine spätere Umentscheidung unwahrscheinlich. Wenn Eurer Team in bestimmten Ausnahmefällen von dieser Entscheidung abweicht, ist es erst recht lohnenswert, diese Tatsache festzuhalten und das Wissen darum zum Beispiel an Neue weiterzugeben. Merke: Dokumentation unterstützt Kommunikation.

Neben den dokumentierten Entscheidungen gehören vor allem Lösungskonzepte und Mittel, die es leichter machen im Quelltext zurecht zu finden, in Eure Architekturdokumentation. Zu letzteren gehören Diagramme, die Strukturen und Abläufe zeigen (ungeliebte und unangefochtene Notation: UML). Die Wahrscheinlichkeit, dass Konzepte und Diagramme veralten, nimmt mit dem Detaillierungsgrad zu.

Veraltete Dokumentation weicht von der Lösungsrealität (dem Quelltext) ab. Das Team hat Änderungen und Ergänzungen also nicht nachgezogen.

Ich lese diese Regel daher vor allem so: Wenn Ihr merkt, dass Ihr viel Aufwand zum Nachziehen betreiben müsst, fragt Euch, ob dieser in einem gesunden Verhältnis zum Nutzen steht. Falls nein: Abstrahieren oder Automatisieren:

• Abstrahieren – die Dokumentation beschreibt keine Lösungsdetails, sondern liefert einen Überblick
• Automatisieren – Teile der Dokumentation werden z.B. im Rahmen des Builds aus dem Quelltext abgeleitet

Und die anderen Regeln?

In einem weiteren Beitrag hier im Blog führe ich die Diskussion mit den verbliebenen zwei Regeln fort. Bleibt dran …