VIDOC

Einführung
Dokumentation entsteht bei der Entwicklung, der Konfiguration und dem Betrieb einer Maschine oder Anlage. Speziell modulare Systeme benötigen eine ebenso modulare Dokumentation damit System und Maschine wirklich jederzeit zusammen passen.

Anforderungen und Herausforderungen

Wer schon einmal Dokumentationen entwerfen musste, die modular und wieder verwendbar sein sollte kann ein Klagelied darüber singen. Es müssen dazu sehr genau Schnittstellen und Formate bezüglich der Inhalte und der sprachlichen Gestaltung definiert werden, damit die Zieldokumente ein harmonisches Ganzes ergeben, auch dann wenn die Quelldaten neu kombiniert werden. Dies gilt insbesondere wenn die Dokumente durch automatische Verfahren zusammengeführt werden.
Die verbreiteten Textverarbeitungs- und Desktop-Publishing-Programme unterstützen Modularität entweder garnicht oder sehr unflexibel. Auch eine automatisierte Verarbeitung stößt schnell an Grenzen wenn die eingebauten Funktionen dazu nicht ausreichen.
In der Regel gibt es auch kein brauchbares Austauschformat oder die Dateiformate sind nicht offen gelegt, was auch den Einsatz von Drittanbieter-Software unmöglich macht. "Open Document" Projekte sind zwar in der Diskussion aber noch nicht wirklich verfügbar.
Noch einmal die Anforderungen an eine angemessene Dokumentationsplattform:
Strikte Trennung von Inhalt und äusserer Form.
Offen gelegtes Dateiformat, das die Bearbeitung durch automatische Verfahren zuläßt.
Die Möglichkeit, Fragmente in Datenbanken zu halten.
Paralle mehrsprachige Bearbeitung und Inhalte.
Unterstützung von fremdsprachlichen Zeichensätzen.
Flexibilität bei der Erzeugung verschiedener Arten von Zieldokumenten.
Bearbeitung der Quelldokumente mit zukunftssicheren Werkzeugen.

Ein Lösungsansatz

VIDOC ist aus den oben geschilderten Anforderungen entstanden. Weder Word, noch OpenOffice, PageMaker oder FrameMaker erfüllen diese Anforderungen zufrieden stellend. Für jedes Programm gibt es gewichtige Argumente, sei es Einfachheit der Bedienung, Gewohntheit oder Stabilität. Es gibt aber genau so viele Gegenargumente und keines der Programme unterstützt Modularität explizit.
VIDOC ist eine Abwandlung des weit verbreiteten und bewährten "DocBook". Da die DocBook-DTD für VIDOC erweitert wurde darf VIDOC nicht DocBook heissen, trotzdem gebührt den DocBook-Machern der Ruhm und unser Dank.
VIDOC beruht auf folgenden Konzepten:
Strikte Trennung von Inhalt und äusserer Form.
Alle Quelltexte werden als XML-Textdateien erzeugt und gespeichert.
Alle Textdateien sind UTF-8 (Unicode) kodiert.
Durch Programme und Konversionsregeln (XSL-Transformationen) werden verschiedene Arten von Zieldokumenten erzeugt.
HTML Zieldokumente bekommen eigene CSS Stylesheets.
Modulare Dokumentation ist immer auch mit Kompromissen behaftet. Für Stil und Inhalte muss es Regeln geben und nicht alles was eine Textverarbeitung hergibt darf auch benutzt werden. Innerhalb dieses Korsetts erfüllt VIDOC jedoch alle oben formulierten Anforderungen. Das Dateiformat XML in UTF-8 Encoding deckt alle sprachbezogenen Anforderungen ab. Mehrere Sprachen in einem Dokument sind unproblematisch und durch entsprechendes Markup auch erkennbar. Die Bearbeitung erfolgt mit Text-Editoren, die zwar nicht die Fähigkeiten eines DTP-Programms haben, die dafür aber auch keine eigenmächtigen Änderungen an den Dokumenten vornehmen.
DocBook wurde ursprünglich zur Herstellung von Handbüchern entwickelt und kennt daher alle Aspekte des "Publishing": Bücher, Bücher-Sets, Artikel, Absätze, Zitate, Verzeichnisse und so weiter. Absätze können zu Artikeln oder Büchern, Artikel zu Büchern und Textschnipsel zu Absätzen zusammen geführt werden. Durch XML sind die Fragmente immer strukturiert und auch von automatisierten Verfahren effektiv zu bearbeiten. Auch die Manipulation eines Textes, z.B. das Ersetzen eines Produktnamens kann durch Software erfolgen.
Für modulare Systeme wie VISTA hat VIDOC den großen Vorteil, dass Bestandteile z.B der Projektdokumentation unmittelbar in VIDOC-Dokumente eingepflegt werden können. Ganze Kapitel z.B. eines Kundenhandbuchs können so automatisch aus den Projektdaten erzeugt werden.
XML Dokumente sind zwar gut lesbar aber natürlich nicht für den Endverbraucher gedacht. Vielmehr werden so genannte XSL-Stylesheets (XSL=eXtensible Stylesheet Language) verwendet, um aus den Quelltexten Zieldokumente zu erzeugen. Nur die XSL Transformationen entscheiden darüber, welche Bestandteile in welcher Form in das Zieldokument gelangen. Standardmäßige Transformationen gibt es u.a. für PDF, HTML, Windows-Help und RTF. Transformationsregeln für andere oder zukünftige Dateiformate können jederzeit entwickelt werden, ohne dass die Quelltexte auch nur angetastet werden müssen. So entstehen aus denselben Texten ein Online-Handbuch in HTML und als PDF.
Die Erzeugung von HTML Texten als Zielformat liegt nahe da HTML und XML verwandt sind und weil immer mehr Dokumentation auf dem Arbeitsplatzrechner direkt auf dem Bildschirm betrachtet wird als in Form gedruckter Bücher. In diesem Fall kommt die Möglichkeit dazu, den endgültigen Stil der Anzeige durch CSS-Stylesheets zu bestimmen. Mit einem modernen Browser ergibt das ansprechende Ergebnisse und wenn sich Ihr "Corporate Design" ändert, ändern Sie einfach das Stylesheet.
Dass man mit VIDOC nicht nur Handbücher entwerfen kann zeigt diese Web-Site, die komplett in VIDOC formuliert und automatisiert in XHTML umgewandelt wurde. Die Quelltexte sind dabei wesentlich einfacher und klarer formatiert als der entstandene HTML-Text vermuten lässt.

Unser Angebot

Wenn Sie ähnliche Anforderungen haben wie wir, sprechen Sie uns bitte an. Wir bieten die Konzeption VIDOC- oder DocBook-gestützter Dokumentation inklusive der Software für deren automatisierte Bearbeitung an.