Die Dokumentation von Software ist eine Aufgabe, die den wenigsten Leuten Spass macht. Und die mit dem falschen Werkzeug endgültig zur Qual wird – unter Umständen auch für den Leser, wenn beispielsweise Referenzen fehlen oder unhandliche Formate zur Verfügung stehen.
Neben dem inhaltlichen Aspekt beeinflussen etliche weitere Kriterien die Qualität einer Dokumentation. Als Leser wünscht man sich verschiedene Formate wie HTML oder PDF, aus denen man dasjenige auswählen kann, das der eigenen Arbeitsweise am meisten entgegenkommt. Dazu sollte man sich gut durch das Dokument navigieren können, damit man schnell zu den gesuchten Informationen gelangt.
Für die Autoren ist es nicht nur wichtig, die Anforderungen der Leser zu erfüllen, sondern die Dokumente auch einfach und plattformunabhängig editieren zu können. Dazu gehört auch, dass sich verschiedene Revisionen problemlos vergleichen lassen, beispielsweise mit GNU diff oder der Versionskontrolle der Wahl, und dass man – was bei der Arbeit im Team wichtig ist – gleichzeitig an verschiedenen Stellen im Dokument arbeiten kann. Ausserdem sollten sich viele bibliographische Elemente wie Inhaltsverzeichnisse einfach erzeugen lassen und programmseitig für ein einheitliches Aussehen der Dokumentation gesorgt werden.
Wortprozessoren wie Microsoft Word oder der Writer aus OpenOffice.org eignen sich daher denkbar schlecht zur Erzeugung von Dokumentationen. Ihre binären Dateiformate (auch die XML-Formate der Suiten werden gezippt) lassen sich schlecht versionieren, die gleichzeitige Arbeit im Team ist nur über Umwege zu bewerkstelligen. Die Erzeugung verschiedener Ausgabeformate abseits von PDF ist nur in sehr rudimentärer Form möglich, und die Einhaltung eines einheitlichen Aussehens der Dokumente benötigt viel Selbstdisziplin. Ausserdem ist Word für seine chronische Schwäche bei der Erstellung grösserer Dokumente und bibliographischer Elemente wie beispielsweise Inhaltsverzeichnisse berüchtigt.
Rein textbasierte Systeme wie LaTeX oder Restructured Text (Bestandteil der Docutils) machen insbesondere bezüglich Versionierung und Stabilität bei grösseren Dokumenten eine bessere Figur, bieten allerdings in Hinsicht auf die Vielfalt bei den Ausgabeformaten oder den Auszeichnungsmöglichkeiten von speziellen Elementen wie Code nur ein eingeschränktes Feature-Set. Dies kann aber auch bei kurzen Dokumenten zusammen mit einer Markup-Sprache wie Restructured Text, die auf eine hohe Lesbarkeit in ihrer Ursprungsform ausgerichtet ist, ein Vorteil sein. Wer dagegen grössere Dokumentationen verwalten muss, dem könnte DocBook gefallen.
DocBook ist eine Markup-Sprache, die wie XHTML auf XML basiert. Sie eignet sich nicht wie XHTML für Webseiten, sondern eben für Dokumentationen. DocBook wurde Anfang der 90er Jahre unter anderem vom Buchverlag O’Reilly entwickelt, der DocBook noch heute als Ausgangsformat für seine Bücher verwendet. Es basierte anfangs noch auf SGML, das mit Hilfe von DSSL Style Sheets in das jeweilige Ausgabeformat übersetzt wurde. Mit der Zeit wurde die Entwicklung von DocBook an die OASIS (Organization for the Advancement of Structured Information Standards) übergeben und SGML durch XML abgelöst, das nun mit XSLT Style Sheets in die gewünschten Formate übersetzt wird.
Wer eine Dokumentation erstellt, tut dies also in Form eines strukturierten XML-Dokuments, das erst mit der Transformation in ein bestimmtes Format gebracht wird. So profitiert man nicht nur von den Vorzügen einer textuellen Quelle, die sich leicht editieren und versionieren lässt, und einer Vielzahl möglicher Ausgabeformate, sondern auch davon, dass sich DocBook mit bestehenden XML-Werkzeugen verarbeiten lässt. So kann man nicht nur seinen (XML-)
Editor behalten und auf bewährte Tools setzen, sondern auch auf etliche XML-Funktionen zurückgreifen, die die Arbeit an grossen Dokumenten deutlich vereinfachen. Zu nennen wären beispielsweise XInclude, mit dessen Hilfe sich grosse Dokumente in viele kleinere aufspalten lassen, oder Schema-Unterstützung, die sicherstellen kann, dass das gesamte Dokument im vorgegebenen Format vorliegt.
Die Erstellung eines DocBook-Dokuments hat sehr viel Ähnlichkeit mit dem Bau einer HTML-Seite. Wie bei einer HTML-Seite werden die Inhalte mit verschiedenen Tags ausgezeichnet. Mit ihnen wird bestimmt, ob ein Textfragment im Ausgabedokument beispielsweise in einen Titel oder eine Fussnote umgesetzt wird.
Die Tags, die verwendet werden dürfen, werden vom DocBook-Standard vorgegeben, der momentan in Version 4.5 vorliegt und so ziemlich jedes Struktur-Element abbildet, das man sich in einer Dokumentation vorstellen kann. Vom Titel über Fliesstext bis hin zur eingebetteten Grafik im SVG-Format ist alles möglich. So sind auch Auszeichnungen für GUI-Elemente, wie man sie in Desktop- oder Webapplikationen findet, möglich.
Für die Autoren macht dies die Einarbeitung in DocBook nicht ganz einfach, da man eine Vielzahl von Tags kennen muss. Die Handvoll Tags, die man häufig benutzt, sollte man trotzdem ziemlich bald beherrschen.
Dieser Funktionsumfang erfordert es aber auch, dass bereits früh im Dokumentationsprozess eine Art Style Guide definiert wird, der den Autoren erklärt, welche Textfragmente sie wie auszeichnen müssen – wenn überhaupt. Denn der DocBook-Standard schleppt einiges an Ballast und auch an redundanten Auszeichnungen mit, was es nicht immer ganz einfach macht, den richtigen Tag für die richtige Aufgabe zu wählen, selbst wenn man die Dokumentation konsultiert. Immerhin sollte sich dieses Problem mit DocBook 5 zumindest teilweise erledigen, da etliche Auszeichnungen gestrichen oder zusammengefasst wurden. Dies wurde unter anderem durch den Wechsel der Schema-Sprache von W3C XML Schema auf RelaxNG (REgular LAnguage for XML Next Generation) ermöglicht.
Hat man sein Dokument beisammen, muss man es in das oder die gewünschten Ausgabeformate transformieren. Dazu reicht ein beliebiger XSLT-Prozessor, sofern er in der Lage ist, mit den komplexen DocBook Style Sheets umzugehen. Das wohl beste Werkzeug zu diesem Zweck ist xsltproc, das auf der libxml2 basiert und einer der schnellsten XSLT-Prozessoren ist. Sablotron soll sich ebenfalls zur Übersetzung der Quellen eignen.
Je nach Ausgabeformat muss man xsltproc mit unterschiedlichen Style Sheets füttern. DocBook XSL bringt unter anderem Style Sheets für verschiedene HTML-Versionen (Einzelseite, mehrere Seiten), Eclipse Sidebars, RTF oder CHM (Compiled HTML Help) mit. PDFs können nur über den Umweg XSL-FO (XSL Formatting Objects) erstellt werden. Hat man aus den DocBook-Quellen ein XSL-FO-Dokument generiert, kann es beispielsweise mit Apache FOP in ein PDF verwandelt werden.
Dass man die DocBook-Quellen erst einmal transformieren muss, um sie überhaupt lesen zu können, ist einer der Nachteile von DocBook, da es eine grössere Umstellung im Arbeitsprozess bedeutet. Schliesslich kann sich nicht jeder Autor beim Schreiben ausmalen, wie sein nacktes XML-Dokument schlussendlich aussehen wird. Da deshalb die Quellen häufig übersetzt werden, lohnt es sich, diesen Prozess für die Autoren möglichst transparent zu gestalten.
Das Mittel der Wahl dürfte die Bereitstellung eines Build-Prozesses sein. Dieser lässt sich beispielsweise mit Hilfe des Java-Werkzeugs Apache Ant und passenden Ant-Tasks definieren. Dies dürfte sich anbieten, wenn die Dokumentation auch auf Windows übersetzt werden soll und die Autoren keine unixoide Umgebung wie Cygwin installieren sollen. Sonst bietet sich die Verwendung von Makefiles für GNU make an, sodass man die DocBook-Quellen mit einem simplen ./configure && make erzeugen kann.
Übersetzen lassen sich DocBook-Quellen auf allen Systemen, auf denen entweder ein Java Runtime Environment oder die wichtigsten GNU-Werkzeuge sowie libxml2 vorhanden sind. Somit kommen Windows, MacOS X und so ziemlich jedes unixoide System von BSD über Linux bis hin zu Solaris in Frage. Zwar gibt es Geschwindigkeitsunterschiede zwischen den einzelnen Systemen: So ist die XSLT-Transformation auf MacOS X beispielsweise langsamer als auf Linux. Bei der Geschwindigkeit heutiger Computer ist der Unterschied aber vernachlässigbar. Für Windows steht mit dem DocBook Environment von E-Novative sogar eine spezielle DocBook-Umgebung zur Verfügung (www.e-novative.info/software/ede.php).
Ein Übersetzungsprozess nach HTML dauert bei einem 150-Seiten-Dokument mit etwa halb so vielen Bildern auf einem aktuellen Computer unter eine Minute. Er kann aber, wenn man nicht aufpasst, schnell auch über 10 Minuten dauern. Dies passiert, wenn der XSLT-Prozessor für die Abfrage der DTDs und der Schemas auf das Internet zugreifen muss. Beheben lässt sich dies, indem man Schemas und DTDs lokal mit Hilfe sogenannter XML-Kataloge vorhält, die die Remote-URLs auf das lokale System umbiegen.
Als Editor eignet sich so ziemlich jeder bessere XML-Editor. Allerdings ist es auf Dauer praktisch, wenn er einen mit Syntax Highlighting und Completion unterstützt und zudem die Dokumente bereits beim Schreiben validiert. Ein einigermassen praktisches und vor allem plattformunabhängiges Werkzeug, das sich mit DocBook versteht, ist die Eclipse Web Tools Platform. Es existieren auch vereinzelte Ansätze für WYSIWYG-DocBook-Editoren, doch taugen diese nur begrenzt für den Einsatz. Ein Beispiel ist Vex, ein Eclipse-Plug-in.
Wer DocBook einmal in Aktion sehen möchte, kann dies vermutlich beim Open-Source-Projekt seiner Wahl tun – DocBook hat sich nämlich als De-facto-Dokumentationsstandard im Open-Source-Bereich etabliert. Auf die Fähigkeiten von DocBook wird unter anderem bei PHP, Subversion, Samba, FreeBSD, KDE und GNOME gesetzt.
