Oct
05
2009

Technische Dokumentation 2.0 – Teil 1: XML statt Word

Wie schon im letzten Beitrag angekündigt, möchte ich die einzelnen Schritte, die bei der Umstrukturierung des Dokumentationsprozesses durchgeführt wurden näher beschreiben. Im ersten Teil geht es um die Umstellung des Basisformates von Word auf XML. Zunächst eine kurze Beschreibung des Dokumentationsprozesses vor der Umstellung auf XML:

Erstellung der technischen Dokumentation mit Word

Die technische Dokumentation bei Saperion wurde nach dem Single-Source Verfahren erstellt. Das bedeutet, dass aus einem Quellformat alle gewünschten Zielformate erstellt werden. Das Quellformat war Word, die Zielformate PDF, DOC und HLP.

Die Dokumentation der Software ist Teil der Software. Genauso wie der Quellcode von SAPERION wird die Dokumentation in den entsprechenden Zweigen in Subversion abgelegt. Als Ablageformat wird PDF verwendet, da in diesem Format alle Elemente der Dokumentation (inklusive Schriften und Bilder) enthalten sind. Für die Erzeugung der einzelnen Ausgabeformate werden spezielle Programme verwendet (Acrobat, Doc2Help).

Bevor die Ausgabeformate erstellt werden können, mussten selbst geschriebene VBA-Scripte ausgeführt werden, die eine Validierung und Konvertierung der Worddateien vornehmen. Schematisch sah der Dokumentationsprozess folgendermaßen aus:

schema-Word

Die Verwendung von Word als Basisformat für die Dokumentation brachte eine Menge Probleme mit sich:

  • Das verwendete Ablageformat (PDF) und das Sourceformat (DOC) sind binäre Formate. Änderungen in der Dokumentation können daher nicht automatisch ausgegeben werden, wie dies bei Textformaten der Fall ist. Um Änderungen zwischen einzelnen Dokumentenrevisionen herauszufinden, müssen die jeweiligen Vergleichsroutinen der verwendeten Programme (Acrobat, Word) benutzt werden
  • Die Dokumentation kann nicht automatisch bei der Generierung eines Builds erzeugt werden. Die Erzeugung der Dokumentation muss in einem separaten Prozess manuell angestoßen werden. Sowohl die Vorbereitung der Worddateien für die Konvertierung (über VBA-Makros) als auch die eigentliche Konvertierung werden dabei manuell angestoßen.
  • Da als Sourceformat DOC und zur Hilfegenerierung eine auf Word basierende Applikation (Doc2Help) verwendet wird, ergibt sich eine extreme Abhängigkeit von der Textverarbeitung Word. Gerade bei Versionswechseln (z.B. Word 2000 => 2003) hat sich aber gezeigt, dass eine 100%ige Kompatibilität nicht gegeben ist. Dies hatte zur Folge, dass z.B. bestimmte Scripte unter Word 2003 nicht laufen und angepasst werden mussten.

Lösungsansatz XML-Dokusystem

Um die oben beschriebenen Probleme lösen zu können, war es erforderlich, das Dokumentationssystem grundlegend zu ändern. Dabei sollte das neue System folgendes bieten:

  • textbasiertes Sourceformat
  • Konsequente Trennung von Inhalt und Layout
  • Einbindung der Dokumentationserstellung in den automatischen Buildprozeß
  • Grafischer Editiermodus (ähnlich Normalansicht Word)
  • Navigation im Dokument (Strukturleiste mit Kapitel, Unterkapitel usw.)

Als Sourceformat wurde XML, genauer gesagt DocBook-XML ausgewählt. DocBook-XML ist ein seit Jahren in der Praxis bewährtes Format für das es viele Anwendungen und Erweiterungen gibt.  Außerdem wurde es speziell für die technische Dokumentation entwickelt. Bei der Suche nach dem richtigen Editor wurde zunächst ein Versuch mit Word selbst unternommen, der aber sehr schnell fallengelassen werden musste, da das von Word produzierte XML nicht verwendbar war. Die zweite Wahl war OpenOffice, dessen Format bereits auf XML basiert und direkt Docbook unterstützt. Allerdings werden bisher durch das Docbook-Projekt von OpenOffice noch nicht alle benötigten Elemente unterstützt, so dass auch diese Variante nicht verwendet werden konnte.

Schließlich haben wir uns für den XML Editor Syntext Serna entschieden, nach einem Vergleich mit XMetal und XMLSpy. Genau wie diese kostenpflichtigen Editoren bietet Serna eine grafische Bearbeitung der XML-Dokumente ähnlich der Normalansicht bei Word. Seit kurzem gibt es Serna als kostenlose Opensource Variante. Das nachfolgende Bild zeigt beispielhaft, wie die Arbeit mit Syntext Serna aussieht (Quelle: Serna Homepage):

serna-on-vista

Anpassung des Dokumentationsprozesses an XML als Sourceformat

Da das Basisformat geändert wurde, musste auch der Dokumentationsprozess dementsprechend angepasst werden. Über einen XSL-Prozessor (Saxon) werden aus den XML-Dateien über XSL-Stylesheets (DocBook-XSL) die Outputformate bzw. Zwischenformate (XSL-FO, HTML) generiert.

PDFs werden über einen XSL-Formatter (FOP) aus dem Zwischenformat XSL-FO erstellt. Onlinehilfen (CHM) werden über den HTML Hilfe Compiler (hhc.exe) aus dem Zwischenformat HTML erstellt. Der neue Dokumentationsprozess sieht jetzt so aus:

schema-XML

Post to Twitter Post to Delicious Post to Digg Post to Facebook Post to MySpace

Download PDF
Written by Karsten Krumrück in: company,deutsch,general | Tags: , ,

1 Comment »

  • Tom

    Gratulation für den Umstieg! :-)
    Mit Sicherheit ist diese Lösung flexibler als mit Word. Das Schöne daran ist, dass man es später noch um zusätzliche Dinge erweitern kann, falls der Bedarf sich ändert. Und man kann über XSLT viele Formate erzeugen, die mit Word so nicht möglich sind.

    Weiterhin viel Erfolg! :-)

    Comment | 9 October 2009

RSS feed for comments on this post. TrackBack URL

Leave a comment


8 + nine =

Theme: TheBuckmaker.com Web Templates | Bankwechsel Umschuldung, Iplexx IT Solutions