Big Brother -- Dokumentieren im Container

Wenn ich in Seminaren unterschiedliche Definitionen für den Begriff „Softwarearchitektur“ vorstelle, sorgt eine stets für Heiterkeit: „Software architecture is what software architects do“ (ein Zitat von Kent Beck, [1]). Aus dem Satz kann man Verschiedenes ableiten, vor allem auch: Wer etwas über Architektur lernen will, sollte Architekten bei der Arbeit zuschauen, beziehungsweise deren Arbeitsergebnisse studieren! Das geht vergleichsweise einfach. Zumindest gibt es eine große Kategorie von Softwarevorhaben, die sich wunderbar auf die Finger schauen lässt: Open Source Projekte. Oft führen diese ihre Kommunikation öffentlich; jeder kann die Mailing-Liste der Entwickler abonnieren, und ist quasi live dabei wie bei Big Brother.

Warum sollte man gerade Open Source Projekte beobachten? Es ist heute unbestritten, dass Open Source so manche Erfolgsgeschichte geschrieben hat. Gerade in der Java-Welt, aber nicht nur dort, dominieren einzelne Lösungen ihr jeweiliges Marktsegment völlig, oder haben zumindest einen signifikanten Marktanteil. Sie bauen also erfolgreiche Software. Den Lenkern dieser Projekte bei der Arbeit zuzuschauen könnte also lehrreich sein. Und tatsächlich geht Open Source mit bestimmten Themen regelmäßig vorbildlich um, insbesondere verglichen mit vielen Projekten der freien Wirtschaft. Der Build-Prozess zählt oft dazu, oder die Art zu Testen. Architekturentscheidungen werden in den Projekten oft per Abstimmung auf Mailing-Listen getroffen, und sind somit sowohl transparent, als auch nachvollziehbar. Sie sind in den Mailarchiven allerdings in der Regel nur schwer auffindbar, und erfüllen nicht den Zweck, den gut dokumentierte Architekturentscheidungen haben könnten [2]. Generell wird Dokumentation als Schwäche von Open Source Projekten angesehen.

Abb. 1: Googlen nach Open Source und Dokumentation

Googlen mit den Begriffen „Open Source Documentation“ bringt viele einschlägige Beiträge zu Tage (vgl. Abbildung 1). Umgekehrt kann man nach „Why Open Source sucks“ suchen. Stets findet man Dokumentation als zentralen Punkt, der den Erfolg von Open Source behindert. Die Gründe für fehlende Qualität sind vielschichtig. Einer ist sicherlich, das Dokumentieren gemeinhin als nicht besonders sexy gilt.

Lässt sich trotzdem Interessantes zum Thema Dokumentation im Open Source Container beobachten? Ich finde schon, denn zum einen gibt es auch positive Beispiele, und zum anderen stellen sich die Projekte die gleichen Fragen wie Sie, und diskutieren sie öffentlich. Ein interessanter Beobachtungspunkt ist zum Beispiel die Tool-Frage („Wie erstellen und veröffentlichen wir Dokumentation?“). In Open Source Projekten haben sich hier zwei grundlegende Strategien etabliert:

Variante 1: Dokumentiert wird in Dateien unter Versionsverwaltung. Als Format kommt bevorzugt XML zum Einsatz (z.B. xdoc, DocBook). Aus den Dateien wird dann die eigentliche Dokumentation generiert, zum Beispiel im Rahmen des Build-Prozesses mit Maven, und anschließend veröffentlicht.

Variante 2: Die Dokumentation wir online editiert, und steht unmittelbar zur Verfügung. Hier kommen vorzugsweise Wikis zum Einsatz. Viele Apache-Projekte fahren dieses Ansatz (Wicket, Geronimo, Felix, …), und nutzen Confluence als Editierwerkzeug. Aus den Wiki-Seiten wird dann automatisch „statische“ Dokumentation auf der Webseite generiert.

Beide Ansätze bringen Vor- und Nachteile mit sich; Apache Ivy-Kopf Xavier Hanin diskutiert sie in seinem Blog [3]. Generell gewinnt Dokumentation in Open Source Projekten an Aufmerksamkeit. Das zeigen einschlägige Konferenzbeiträge wie beispielsweise das interessante „Documentation: get it right!“ von Niels van Kampenhout auf der diesjährigen ApacheCon Europe [4]. Niels führte etwa aus, dass veraltete Dokumentation unbedingt vom Netz muss; sie schade mehr als sie nutzt. Weiterhin ist die Organisation der Dokumentation nach Zielgruppen ein zentraler Erfolgsfaktor, er empfahl spezielle Tracks z.B. für Endbenutzer, Entwickler, Administratoren. Und nicht zuletzt führte er die Probleme aus, die der Einsatz eines Wikis zur Dokumentationserstellung mit sich bringen kann. Dieser Punkt führte zu einer sehr lebendigen Diskussion; viele Teilnehmer hatten hier ähnliche Erfahrungen gemacht. Wenn sich keiner verantwortlich für die Gesamtdokumentation fühlt, ist ein Wiki Garant für veraltete Inhalte, Fragmentierung, fehlende rote Fäden. Umgekehrt ließe sich dem aber gut vorbeugen durch das Schaffen einer Rolle, der die Verantwortung für das Ganze übertragen wird („Doctator“).

Wann funktioniert Dokumentation in Open Source gut? Oft ist sie Ergebnis des Drucks auf der Mailingliste. Wenn zu einem bestimmten Themenkomplex immer wieder Fragen auftauchen, die nicht mit einem Verweis auf die Dokumentation beantwortet werden können, ist dort offensichtlich ein Mangel. Im Idealfall wird dieser schnell behoben, die Dokumentation ist bedarfsgetrieben.

Erfolgreiche Open Source Frameworks etwa veröffentlichen oft eine exzellente Dokumentation ihrer Architektur. Da ein Framework benutzt wird, indem man es erweitert, ist dies auch unabdingbar. Beispiel gefällig? Schauen Sie sich die Dokumentation von Hibernate an!

Links & Literatur

[1] P. Kruchten, “What do software architects do?”, April 2006
[2] S. Zörner, “Historisch gewachsen? - Entscheidungen festhalten”, Java Magazin 4/2009
[3] Xavier Hanin, “Open Source documentation dilemna”, http://xhab.blogspot.com
[4] ApacheCon Europe 2009, http://www.apachecon.com/c/aceu2009/

Zuerst erschienen hier:
Stefan Zörner: Kolumne Architekturen dokumentieren.
“Big Brother – Dokumentieren im Container”, Java Magazin, 06/2009, 2 Seiten, S. 105
(mit freundlicher Genehmigung)