Alles im Griff
Projektdokumentation mit reStructuredText und Sphinx
Mögliche Kandidaten: Wikis
Basierend auf den formulierten Anforderungen kommen diverse Tools in Frage, die sich alle mehr oder weniger für Projekt-Dokumentationszwecke eignen. Häufig kommen bei der Projekt-Dokumentation zum Beispiel Wikis zum Einsatz. Diese erfüllen einige der genannten Kriterien und sind bereits ein deutlicher Fortschritt zur Ausgangssituation.
Wikis haben üblicherweise eine eigene Markup-Sprache, mit der sich Inhalte formatieren und strukturieren lassen. Durch die Implementierung als Webservice ist eine deutlich leichtere Teamarbeit möglich - jeder Wiki-Nutzer ist in der Lage, schnell und relativ komfortabel Änderungen an bestehenden Seiten vorzunehmen oder neue Kapitel zu erstellen. Die meisten Wikis bieten standardmäßig eine eingebaute Versionskontrolle, mit der sich die Historie eines Dokuments - „Wer hat wann was geändert?“ - nachvollziehen läßt. Auch die konkreten Differenzen zwischen zwei Dokument-Versionen können dargestellt werden.
Bei Wikis gibt es unzählige Optionen: neben dem Klassiker MediaWiki etwa auch DokuWiki, MoinMoin oder Twiki. Auch das proprietäre Confluence-Wiki von Atlassian ist sehr populär. Hier heißt es sehr genau abzuwägen, welche Funktionalität erfordert wird, wie sich das Wiki in bestehende Infrastruktur integriert und wie komfortabel man es bedient.
Während Wikis beim Thema Kollaboration punkten, haben sie jedoch einige systemimmanente Einschränkungen. Zum einen wäre zu nennen, dass sie neben der HTML-Ausgabe im Web-Browser meist kaum oder gar keine weiteren Ausgabeformate unterstützen. Der PDF-Export einer einzelnen Seite ist meist noch möglich. Aber wenn es darum geht, die Inhalte vieler Seiten als strukturiertes Dokument zu generieren, sind eher kreative Lösungen gefragt. Damit einher geht, dass die Erzeugung von Dokumentation mit einem Wiki häufig schlecht automatisierbar ist.
Weiterhin besteht immer noch ein Medienbruch zwischen Projekt-Code und Dokumentation. Der Entwickler muss kognitiv einen Kontextwechsel vollziehen, um nach der Veränderung des Codes die Dokumentation im Wiki nachzuziehen. Das erschwert insbesondere die Synchronisation zwischen Code und Dokumentation. Auch die Pflege mehrerer Versionen eines Dokuments erfordert manuelle Arbeit: Änderungen, die mehrere Versionen eines Projekts betreffen, müssen händisch per Cut & Paste in die entsprechenden Seiten oder Kapitel übernommen werden.
Markup und Buildchains
Um den Medienbruch zwischen Projekt-Code und Dokumentation zu vermeiden, bietet es sich an, auf Markup-Sprachen als Quelltext der Dokumentation zurückgreifen und diese als Text-Dateien zusammen mit dem Projekt-Code zu speichern. Solche Quelltextformate versprechen, sich in unterschiedliche Ausgabeformate exportieren zu lassen, ähnlich wie ein Compiler aus Quellcode ein Executable für verschiedene Plattformen kompiliert.
Der Artikel von Patrick Koetter in der Sommer-Ausgabe der UpTimes [1] zeigt, welche Markup-Formate sich im Laufe der Zeit entwickelt haben, und stellt die Eigenschaften der geläufigsten Auszeichnungssprachen gegenüber. Zusätzlich zu den dort vorgestellten Markup-Dialekten wäre noch Textile erwähnenswert, das oft bei der Konvertierung in HTML-Format etwa bei Foren- oder Blog-Software zum Einsatz kommt. Für komplexere Dokumente eignet es sich allerdings weniger. Es gibt, ähnlich wie bei Markdown, über 20 verschiedene Dialekte und Implementierungen, die sich mehr oder weniger stark unterscheiden.
In der Praxis ist wichtig, wie und mit welchem Aufwand sich derart formatierte Quelltexte dann tatsächlich weiterverarbeiten lassen - wie also ihre Buildchain aussieht und welche Frameworks oder Werkzeuge es rund um das Markup-Format gibt. Während DocBook XML extrem leistungsfähig und ein de-facto-Standard für umfangreichere Dokumentationsprojekte ist, so ist es jedoch auch sehr schwergewichtig und erfordert eine steile Lernkurve. Das kann insbesondere unerfahrenene Entwickler abschrecken und damit wieder dazu führen, dass die Dokumentation schlicht nicht gepflegt wird.
Darüber hinaus ist der Quellcode eines DocBook-Dokuments im Original ohne spezielle Editor-Unterstützung nur schwer lesbar, da das Format sehr Markup-lastig ist und der Inhalt somit in den Hintergrund tritt. Auch der Build-Prozess von DocBook-Dokumenten mittels FOP ist durch das verwendete Java recht Ressourcen-intensiv und damit nicht ohne weiteres mal eben auf einer Entwickler-Maschine aufsetzbar. Ähnlich verhält es mit AsciiDoc. Während das Markup-Format an sich sehr schlank ist, benötigt es DocBook für die PDF-Ausgabe, was die Toolchain deutlich verlängert.
