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

Die 10 Gebote blicken auf eine bewegte Vergangenheit zurück. Jahrtausende alt und immer noch gültig nicht nur im christlichen Miteinander.

Der Überlieferung nach in zwei Tafeln aus Stein gemeißelt (drei bei Mel Brooks) und in der Bundeslade verwahrt, hinter der Indiana Jones her war (und die Schurken im Film auch) und die zuletzt auch in James Frey’s Bestseller “Endgame” eine Rolle spielte …

Als die zehn Gebote Einzug in das Alte Testament hielten gab es noch keine Softwareentwicklung. Die Leute hatten andere Sorgen.

Nicht ganz so alt (und weniger berühmt) sind die 7 Regeln für gute Dokumentation (im Original: „Seven rules for sound documentation“). Aber immerhin auch schon fünfzehn Jahre. Gedruckt zwischen die zwei Buchdeckel des englischen Standardwerks zu Architekturdokumentation.

Wer von Euch sie zum Beispiel altersbedingt nicht kennt … Kurz zum Kennenlernen – bzw. zur Auffrischung im Englischen Original:

1. Write documentation from the point of view of the reader, not the writer.
2. Avoid unnecessary repetition.
3. Avoid ambiguity. Always explain your notation.
4. Use a standard organization.
5. Record rationale.
6. Keep documentation current but not too current.
7. Review documentation for fitness of purpose.

Als das betreffende Buch erschien war der Rational Unified Process ebenso topaktuell wie die UML oder J2EE. Seither ist einiges passiert in der Softwareentwicklung.

1. Schreibe aus Sicht des Lesers.	2. Vermeide unnötige Wiederholungen.	3. Vermeide Mehrdeutigkeit. Erkläre Deine Notation.
4. Verwende eine Standardstrukturierung.	5. Halte Begründungen für Entscheidungen fest.	6. Halte Dokumentation aktuell, aber auch nicht zu aktuell.
7. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit.

Ich möchte in diesem und zwei weiteren Beiträgen die obigen sieben Regeln im heutigen Licht diskutieren. Können sie uns heute noch etwas sagen? Oder ist das ganze ein Relikt (dann konservieren wir es mit Lastenheft und Systemtestphase)?

Aus dramaturgischen Gründen gehe ich in einer anderen Reihenfolge vor …

Halte Begründungen fest, oder “Warum solltet Ihr überhaupt dokumentieren?” (Regel 5)

Simon Brown sagt so schön “Der Quelltext erzählt nicht die ganze Geschichte”. Er steht damit im Kontrast zum beliebten Satz “Der Quelltext ist die Dokumentation” (… und darüber hinaus dokumentieren wir nichts).

Wenn es um das Festhalten von Informationen geht hat Quelltext Charme. Er ist in jedem Fall erforderlich, das Team versioniert ihn, testet ihn, er ist stets up-to-date. Und tatsächlich kann man dem Quelltext (oder den zugehörigen und gemeinsam versionierten Build-oder Deployment-Skripten) vieles entnehmen. Welche Fremdbibliotheken verwendet werden beispielsweise. Was genau verschweigt der Quelltext?

Einige Informationen lassen sich dem Quelltext zumindest schwierig entlocken. Die Struktur der Lösung beispielsweise, insbesondere wenn es mehrere Zerlegungsideen gibt (technisch in Schichten, fachlich in Komponenten z.B.). Oder wenn Aspekte über die ganze Lösung hinweg einheitlich gelöst sind und es auch bleiben sollen.

Oft macht der Quelltext zwar die Aussage, dass etwas verwendet wird (beispielsweise eine Fremdbibliothek). Aber ob es die Entscheidung des Teams war es zu verwenden, oder eine Vorgabe, das verschweigt der Quelltext bereits. Und im Falle einer Entscheidung des Teams fehlen Informationen zu in Erwägung gezogenen Alternativen, ebenso zu Bewertungskriterien derselben.

Wenn Nachvollziehbarkeit gefragt ist, reicht der Quelltext oft nicht aus. Wenn etwa ein Neuer im Projekt fragt “Warum habt Ihr das so gemacht? Hätte man ja auch anders …” – da antwortet er nicht. Womit wir direkt bei der nächsten Regel sind.

Schreibe aus Sicht des Lesers (Regel 1)

Klingt vernünftig die Regel, aber beim Nachdenken über Architekturdokumentation wirft sie sofort die Frage auf, wer denn genau dieser Leser ist. Wenn Euch im Team beim besten Willen kein potentieller Interessent für Eure Dokumentation einfällt, solltet Ihr keine schreiben. Dürfte ja keiner merken.

Viele Teams identifizieren jedoch als Zielgruppe sofort den Neuen im Team, oder auch das Entwicklungsteam selbst. Ich mache in Projekten immer sehr Reklame dafür, solche Zielgruppen und deren Informationsbedürfnis (in Form von Zielen) aufzuschreiben. Nicht ausführlich, aber explizit.

Zum Beispiel:

• Der neue im Team – will sich schnell zurecht finden, zur Lösung beitragen, die Software selber bauen und deployen können …
• Ein Teammitglied – will Lösungsansätze anderer im Team nachvollziehen können und sich Good Practices abgucken …

Das heißt nicht unbedingt, dass eine Dokumentation diese Ziele ohne Zutun anderer im Team löst. Dokumentation erspart Euch nicht die Kommunikation. Aber: sie unterstützt dabei, d.h. die Sachen, die über den Quelltext hinaus angefertigt werden, helfen beim Erklären.

Und die anderen Regeln?

In zwei Folgebeiträgen hier im Blog führe ich die Diskussion mit den verbliebenen Regeln fort. Ich habe mir ein paar Highlights aufgespart: die Frage nach Redundanz, Aktualität, Notationen …