Als Menschen, die relativ viel mit Softwareprojekten - besonders im Bereich der quelloffenen Software - zu tun haben, kommen wir sehr häufig auch mit der Dokumentation, die es zu diesen Projekten gibt, in Berührung. Meist sogar eher als mit der eigentlichen Software.
Dabei hat die "Qualität" der Dokumentation einen relativ großen Einfluß darauf, wie die Software bzw. das Softwareprojekt von seinen (potentiellen) Benutzern wahrgenommen wird.
Interessanterweise scheint das Erstellen von Dokumentation in Kreisen von Entwicklern und Systemadministratoren gleichzeitig relativ unbeliebt zu sein. Man kann sogar den Eindruck gewinnen, dass es eine weit verbreitete Einstellung in diesen Kreisen gibt, die das Erstellen von Dokumentation allenfalls als notwendiges Übel wahrnimmt. "Der Sourcecode ist die Dokumentation" oder "Wer das nicht hinbekommt, ist ein noob" sind Aussagen, die zu dieser Einstellung passen.
Nicht zuletzt gibt es besonders im bereich der quelloffenen Software viele Menschen, die davon leben, dass zu Softwareprojekten allenfalls schlechte Dokumentation existiert. Für Einrichtung und Betrieb dieser Software werden dann oft Berater und Betreiber benötigt, die die fehlende Dokumentation ausgleichen - gegen Geld.
Nach den Inhalten geht es auch um die Form und Darstellung der Dokumentation. Wie kann es dem Ersteller möglichst einfach gemacht werden, gute Dokumentation herzustellen? Wie kann Dokumentation ggfs. automatisiert z. B. aus Kommentaren im Sourcecode extrahiert und präsentiert werden? Wie können Fehler in der Dokumentation korrigiert und wie können Ergänzungen eingepflegt werden?
Nur um mal irgendwo in diesem weiten Feld anzufangen, habe ich begonnen, mir die Dokumentationssysteme von verschiedenen Softwareprojekten anzusehen:
Auf den ersten Blick wirkt die Darstellung in allen betrachteten Projekten ähnlich. Es gibt links eine Navigation mit mehr oder weniger sinnvollen Oberbegriffen, die beim Draufklicken weitere Unterpunkte auflisten. Und es gibt ein Suchfeld, welches eine Freitextsuche erlaubt.
OSISM
OSISM - ähnlich wie Openstack - beinhaltet viel Python-Code. Das mag der Grund dafür sein, dass die Dokumentation mit Hilfe von Sphinx generiert wird. Dokumentation in Sphinx wird als ReStructuredText geschrieben, welches Markdown ähnelt von vielen Benutzern aber wohl als schwieriger angesehen wird. Sphinx ist hautpsächlich für die Erstellung von Referenzdokumentation gedacht. Es kann diese Referenzdokumentation aus Python Docstrings extrahieren. Wie viele andere Dokumentationssysteme dieser Art verwendet auch Sphinx docutils, um verschiedene Ausgabeformate (wie z. B. HTML) zu generieren. In der Sphinx-Dokumentation gibt es ein "Getting Started", bei dem man einen Überblick bekommt. M. E. kommt hier klar heraus, dass Sphinx sich als Dokumentationssystem für Software sieht. Aber (zum Glück) ist ja nicht alles Software.
Zephyr
Die Dokumentation zum Zephyr Betriebssystem wird ebenfalls mit Sphinx erzeugt - verwendet aber auch doxygen und das doxygen-awesome-css Theme, um API-Dokumentation zu erstellen. Das Zephyr Projekt hat zu dem Thema "Documentation Generation" eine eigene Dokumentation erstellt, aus der hervorgeht, wie die verschiedenen Softwarekomponenten, die für die Generierung der Dokumentation zum Einsatz kommen, zusammenhängen. Breathe scheint auch noch involviert zu sein.
Syseleven
Die Kundendokumentation des Syseleven Stack kommt zwar optisch ähnlich daher wie die Softwaredokumentation von OSISM und Zephyr - sie wird aber mit dem CMS Grav erstellt. Bei CMSStash gibt es ein Review von Grav. Grav verwendet Markdown als Textformat und bietet offenbar einen Markdown-Editor an. Es ist offenbar eins der am weitesten verbreiteten, quelloffenen Flat-File-CMS. Grav ist offensichtlich ein eigenständiges CMS, welches nicht speziell auf die Dokumentation von Software oder Softwareprojekten ausgerichtet ist.
Openstack
Openstack benutzt ebenfalls ReStructuredText mit Sphinx-Extensions zur Erstellung der Projektdokumentation. Es ist auch eine Anleitung vorhanden, die das Erstellen der Dokumentation auf dem lokalen Arbeitsplatz beschreibt. In so einem großen Projekt wie Openstack mit seinen verschiedenen Unter- und Nebenprojekten gibt es natürlich ein eigenes Doku-Team, welches die Struktur mit Templates, Blueprints und Spezifikationen vorgibt.
SmartOS Wiki
Das SmartOS Wiki verwendet Material for MkDocs - ein Theme für MkDocs - um die Website zu generieren. MkDocs verwendet Markdown als Textformat. Sympathischerweise listet die Dokumentation zu MkDocs auch Alternativen zu MkDocs auf. Dort werden neben Sphinx noch Docusaurus (von Facebook), Jekyll und GitBook aufgeführt.
Generell sind für mich folgende Punkte zur Bewertung eines Dokumentationssystems wichtig:
- Gute und schnelle Suchfunktion
- Die Einstiegshürde, um Dokumentation zu schreiben, muß möglichst gering sein.
- Ein Editor, der die Autoren unterstützt und ein Preview anbietet.
- Anbindung an ein Versionskontrollsystem wie git, um von Funktionen wie Pull-Requests profitieren zu können.
- Kein komplexes CMS sondern idealerweise Flat-File ohne weitere Abhängigkeiten.