© Bredehorn Jens, Pixelio.de

Wer in einem Team an Softwaredokumentationen arbeitet und dabei etwa Open-Office-Dokumente per E-Mail austauscht, der handelt sich leicht Probleme ein, wenn sich Änderungen überschneiden oder die Mitstreiter Formate uneinheitlich gebrauchen. Doch es gibt einen besseren Weg.

Viele kleinere Unternehmen schreiben ihre Dokumentation mit einer Textverarbeitung wie Open Office Writer oder Word. Jeder, der im Team die Datei bearbeitet, kann neben dem Inhalt auch die Formatierung beliebig ändern. Ein einheitliches Layout, insbesondere über mehrere Dokumente hinweg, lässt sich so nur mit einer gehörigen Portion Selbstdisziplin erreichen.

Der Export der Daten in mehrere Ausgabeformate, etwa als PDF-Datei für den Druck, als Satz HTML-Dateien für das Internet und als CHM-Datei für die Onlinehilfe des Windows-Programms ist zwar möglich, aber etwa die Qualität des HTML-Exports einer Textverarbeitung ist dabei kaum zufriedenstellend.

Dazu kommt, dass ab einer gewissen Projektgröße mehrere Mitarbeiter und externe Hilfskräfte das Dokument ergänzen und überarbeiten sollen. Es mag naheliegend sein, die Dateien per E-Mail herumzuschicken. Doch wehe, zwei Autoren bearbeiten das Dokument gleichzeitig! Dann heißt es, sehr gut aufpassen, dass nicht eine der Änderungen verloren geht, und das Zusammenführen ist mühsame Handarbeit. Auch kann man später schwer nachvollziehen, auf wen welche Passage zurückgeht.

Der Retter: Docbook

Diese Probleme lassen sich mit freier Software lösen. Dabei kommt zum einen Docbook zum Einsatz. Dieses XML-Format, HTML nicht unähnlich, beschreibt den Inhalt eines Dokuments auf der semantischen Ebene. Es enthält keine Tags für Formatierungsangaben wie Fett- oder Kursivdruck, stattdessen gibt es eine sehr große Auswahl an Tags wie »<title>« oder »<productname>«. Diese Stilvorgaben verwandelt ein XSLT-Stylesheet erst später in konkrete Formatierungsanweisungen. Die nötigen Werkzeuge dafür sind in den meisten Linux-Distributionen bereits enthalten. So erstellen unter Debian etwa die Anweisungen

xsltproc /usr/share/xml/Docbook/stylesheet
/Docbook-xsl/xhtml/Docbook.xsl
document.xml > document.html

aus der Docbook-Datei »document.xml« eine einzige HTML-Datei und verwenden dabei das Standard-Stylesheet. PDF-Dateien generiert der Anwender über den Umweg einer Fo-Datei:

xsltproc /usr/share/xml/Docbook/stylesheet
/Docbook-xsl/fo/Docbook.xsl
document.xml > document.fo
fop document.fo document.pdf

Dabei ist »fop« der Formatting Objects Processor, der ebenfalls den gängigen Linux-Distributionen beiliegt. Anpassungen nimmt eine eigene XSLT-Datei vor, die das Standard-Stylesheet einbindet. Listing 1 ändert die Papiergröße auf A4 und aktiviert den Draft-Modus, der die Seite mit einem hellgrauen Text »DRAFT« hinterlegt. Das Buch [1] ist die kanonische Referenz zu Docbook, und [2] geht im Detail auf die Möglichkeiten der Anpassung der XSLT-Stylesheets ein. Beide Bücher sind online frei verfügbar.

01 <?xml version="1.0" encoding="UTF-8"?>
02 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
03         <xsl:import
04         href="/usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl" />
05         <xsl:param name="paper.type" select="'A4'"/>
06         <xsl:param name="draft.mode">yes</xsl:param>
07 </xsl:stylesheet>

Ist das gewünschte Layout erst einmal in einen Satz von XSLT-Stylesheets umgesetzt, so erhält man daraus fortan hochwertige und einheitliche Dokumente. Die Autoren, die an den Docbook-Dateien arbeiten, können das Erscheinungsbild nicht mehr gefährden. Außerdem lässt sich später das Layout an zentraler Stelle ändern, ohne dass dabei viele Dokumente händisch zu aktualisieren wären.

Nicht jeder Mitarbeiter wird ein Docbook-Dokument im Quelltext bearbeiten wollen. Hier helfen XML-Editoren, die eine grafische Ansicht bieten, ohne dabei die Trennung von Inhalt und Layout aufzugeben (Abbildung 1). Verwendbar sind beispielsweise der proprietäre Java-Editor XMLmind [3] oder das freie Serna XML [4]. Beide laufen sowohl unter Linux als auch unter Windows.

Abbildung 1: Mit einem XML-Editor wie Serna fällt das Editieren der Docbook-XML-Files relativ leicht. Inhalt und Layout bleiben auch dabei getrennt.

Helfer Nummer zwei: Subversion

Arbeiten mehrere Redakteure an einer Docbook-Quelle, so drängt sich eine Versionsverwaltung (VCS, Version Control System) wie Subversion geradezu von allein auf. Sie erlaubt es jedem Mitarbeiter, sich alle Dokumente auf dem aktuellen Stand auf seinen Arbeitsplatz zu laden, dort lokal zu bearbeiten und sie dann als neue Version wieder im Repository abzuspeichern.

Dabei lässt sich jede Änderung kommentieren und mit Metadaten wie dem Namen des Autors versehen. Die gleichzeitigen Änderungen zweier Redakteure in verschiedenen Abschnitten der Datei führt Subversion später verlustlos wieder zusammen.

Ein recht nützliches Feature von Subversion ist, dass es im Dokument eine Markierung einfügen kann, die die aktuelle Revisionsnummer, das Datum der letzten Änderungen sowie den Namen des letzten Autors angibt. In der englischsprachigen Subversion-Dokumentation [5] heißt diese Funktion »keyword substitution«. Packt der Admin sie in das Docbook-Tag »releaseinfo«, sieht er jedem erzeugten Dokument auf einen Blick seinen Versionsstand an. Das ist besonders dann sehr nützlich, wenn die Seiten ausgedruckter Exemplare im Büro herumliegen.

Unter die Haube

Mit Docbook und Subversion lässt sich bereits ein leistungsfähiges und funktionierendes System aufbauen. Schwierig wird es aber, wenn sich die Installation von Docbook auf den Arbeitsplätzen der Autoren verkompliziert, weil sie als externe Mitarbeiter mit den verschiedensten Betriebssystemen arbeiten. In diesem Fall wird der Admin ihnen einen eigenen Subversion-Client und einen XML-Editor ihrer Wahl zugestehen, die Docbook-Ausgabe aber auf dem Server generieren und dort bereitstellen. Dazu schreibt er ein geeignetes Skript und installiert es als Post-Commit-Hook im Repository.

Zpub

Die freie Software Zpub setzt genau an diesem Punkt an [6]. Sie besteht aus einer Reihe von Perl- und Bash-Skripten, die nach einem Subversion-Commit das geänderte Dokument in den verschiedenen Ausgabeformaten neu erstellen.

Über eine Weboberfläche (Abbildung 2) kann der Anwender anschließend die aktuelle Version wie auch die Vorgängerversionen anschauen und bei Bedarf herunterladen. Auch die Änderungskommentare sind dabei pro Dokument im Archiv enthalten. Auf Wunsch informiert Zpub per Rundmail sogar die anderen Redakteure, sobald es eine neue Version des Dokuments erzeugt hat.

Abbildung 2: Die Historie eines Dokuments in der Zpub-Weboberfläche.

Der Zpub-Administrator kann zwei Stylesheet-Varianten hinterlegen: Eine mit einem so genannten Draft-Stil, der stets bei der neuesten Revision zum Einsatz kommt, und eine andere mit einem so genannten Final-Stil, den nur Benutzer mit den passenden Rechten in der Zpub-Oberfläche auswählen dürfen. Auf diese Weise lässt sich ein einfacher, aber dennoch effizienter Arbeitsablauf etablieren und auch sicherstellen, dass keine Arbeitsversionen versehentlich zu den Kunden gelangen.

Fazit

Dateien als E-Mail-Anhang herumschicken ist so wenig zur Koordination beim gemeinsamen Erstellen einer Dokumentation geeignet, wie eine Textverarbeitung zum Setzen technischer Dokumentation taugt. Subversion und Docbook sind jeweils geeignetere Werkzeuge. Kombiniert können sie Struktur in den Redaktionsprozess bringen. Zusätzliche Funktionalität und Komfort lassen sich mit eigenen Skripten umsetzen.

Eine passende Erweiterung für diesen Zweck ist Zpub, das dem Docbook-Subversion-Gespann eine Weboberfläche verpasst, die Ausgabedateien zentral erzeugt und zusätzlich eine einfache Ablaufsteuerung implementiert. (jcb)