XML, DITA, DocBook, S1000D oder Shipdex – sind Sie verunsichert wenn es um Standards der strukturierten Inhaltserstellung für die technische Dokumentation geht?

Immer mehr technische Autoren, Redakteure und Manager der technischen Dokumentationserstellung beginnen das erhebliche Wertschöpfungspotential von XML als Grundlage für die strukturierte Inhaltserstellung zu verstehen. Eine der ersten Fragen, welche auf den neuen Benutzer und das Unternehmen zukommt ist, was für ein Standard für die Inhaltserstellung benutzt werden soll.
 

Unserer Meinung nach muss der benutzte Standard die organisatorischen, funktionellen und technischen Anforderungen zufriedenstellen und wir können aus Erfahrung sagen, dass ein kompliziertes und allumfassendes Datenmodell in den meisten Fällen nicht von Vorteil ist. Dieser Artikel befasst sich und diskutiert dieses wichtige Thema und wir stellen ebenfalls unseren eigenen „Standard“ namens „TechDok“ vor.

 

Hintergrund

Wir werden vor Implementierungen von unseren Lösungen In vielen Fällen vom Kunden gefragt, was für XML Standards existieren und innerhalb der Industrie des Kunden benutzt werden. Nach einer kurzen Suche auf Google kommen ungefähr 60 verschiedene XML Standards zum Vorschein mit dem Anspruch genau das zu sein,- ein Standard. Das kann den Verantwortlichen für die Auswahl der Technologien und Implementierung schon einmal den Atem nehmen. Lassen Sie uns deshalb mit den Grundlagen beginnen.

Ein XML Dokument unterscheidet zwischen Inhalt, Style und Struktur. The Struktur ist dazu benötigt, um es technischen Autoren bzw. Redakteure zu ermöglichen, denselben Prinzipien und Regeln bei der Inhaltserstellung folgen können. Diese Struktur wird durch eine sogenannte „DTD“ bzw. ein „Schema“ vorgegeben und kontrolliert. Diese sogenannte „DTD“ oder das „Schema“ ist nichts anderes als eine XML Datei, welche vorgibt was für eine Art von Inhalt an welcher Stelle erlaubt ist, wie dieser Inhalt erstellt oder eingefügt werden kann oder was für Inhaltselemente erlaubt sind. Kurzum, zwei technische Autoren bzw. Redakteure, welche die selbe „DTD“ oder das gleiche „Schema“ benutzt haben, können Ihre Dokumente zu jeder Zeit zu einem einzigen Dokument zusammenfügen. Probleme bezüglich von Seitenumbrüchen oder anderen Style –bzw. Anordnungsmerkmalen bleiben damit aus.
 
So weit, so gut. Doch warum gibt es dann so viele verschiedene Standards? Würde nicht eine einzige Struktur mit Hilfe von einer DTD oder eines Schema’s ausreichen? Die Antwort finden wir nach der Untersuchung von verschiedenen industriespezifischen Dokumentationen. Zum Beispiel, der Inhalt und dessen Strukturierung von einem Produkt im Militärbereich (z.B. ein Unterseeboot) ist völlig anders als die Dokumentation eines Softwareproduktes (z.B. das Linux Operationssystem). Aus diesem Grund haben die verschiedenen Industriekörperschaften Ihre eigenen DTD’s oder Schema’s entwickelt. Die am meisten benutzten Standards oder Formen derer sind DITA, DocBook und S1000D (auch Shipdex genannt).

Buch-basierende DTD’s - DocBook

Die am meisten bekannte Form der Veröffentlichung ist das klassische Buch. Das Buch hat eine Titelseite, ein Inhaltsverzeichnis, mehrere Kapitel und eine Rückseite. Die technisch orientierte Veröffentlichung eines Buches beinhaltet auch meistens Unterkapitel und Abschnitte. Durch die breitflächige Verwendung des Buchformates ist fast jeder damit vertraut. Die abstrakte Struktur des Buches mit der Titelseite, dem Inhaltsverzeichnis und Kapitel kann Platzhalter für Inhalte jeglicher Art und Herkunft sein. Das Buch als DTD oder Schema funktioniert!

Es stehen einige DTD Standards zur Verfügung welche auf dem Buchformat basieren und der am meisten bekannte ist Docbook. Docbook selbst ist das Resultat von über 20 Jahren Entwicklung und wird mit jeder gängigen XML Redaktionssoftware (PTC Arbortext Editor, Adobe FrameMaker usw.) dem Nutzer als Standard zur Verfügung gestellt. Die meisten der heutigen DTD’s basieren auf dem Buchformat und daraus ergeben sich die folgenden Vorteile:

1. Dateiformate von Microsoft Word, Adobe Indesign und viele andere lassen sich mit niedrigen Aufwand importieren
2. Einfach erlernbar und umfangreiche Funktionalität
3. Stylesheets lassen sich mit niedrigen Aufwand erzeugen

Themenspezifische DTD’s – DITA

Ein völlig unterschiedliches und im Vergleich zum traditionellen Buchformat stark im Kontrast stehendes Konzept ist die Benutzung von sogenannten „Topics“ (Thematik).

Der am besten bekannte und weit verbreitete Standard bei welchen das Topic als Grundbaustein im Mittelpunkt steht ist DITA (Darwin Information Typing Architecture).



Der DITA Standard wurde in den 90er Jahren von IBM entwickelt, um eine möglichst hohe Wiederverwendung von Informationen zu ermöglichen. Das Hauptanwendungsgebiet war vorerst die Erstellung von Dokumentation für Software.

Um die Topic basierende Struktur am besten zu erklären, könnte man als Analogie eine Webseite benutzen. Bei einer Webseite kann jede einzelne Seite durch ein Topic repräsentiert werden. Alle Seiten zusammen (und demzufolge viele verschiedene Topic’s) ergeben dann das eigentliche Dokument. 

Für eine Webseite ist das eine brilliante Lösung aber wie kann das Konzept des Topic’s verwendet werden um ein Buch zu erstellen?

DITA löst dieses Problem mit einem strukturellen Platzhalter mit dem Namen „Bookmap“. Mit Hilfe dieser „Bookmap“ können alle Topics in der erforderlichen Reihenfolge miteinander verlinkt werden, was für die sinngerechte Veröffentlichung der Dokumente von großer Wichtigkeit ist.

Wie man sich evtl. vorstellen kann, ist es bei der Nutzung von DITA relativ schwierig, bereits existierende Inhalte welche auf dem „Bookformat“ bestehen nach DITA zu migrieren. Für die Software Dokumentation jedoch und auch für alle anderen Inhalte welche letztendlich auf dem Internet veröffentlicht werden sollen, steht mit DITA eine ausgezeichnete Architektur zur Verfügung.

Eine weitere Charakteristik mit DITA ist das die Regeln für die Erstellung von Inhalten viel bestimmter sein müssen als wie zum Beispiel mit Docbook. Der Grund dafür ist das jedes Topic auch allein für sich selbst stehen sollte. Vielleicht erinnern sich einige Leser an ein Spiel in der Schule, wenn jeder einen Absatz auf ein Blatt Papier schreibt und anschließend das Papier faltet und zum nächsten gibt, aber dieser nur den letzten Satz lesen kann? Wenn keine klaren Regeln vorher ausgemacht und auch befolgt werden, kann die Geschichte am Ende sehr lustig ausgehen. 

Vorteile mit DITA:
Sehr hohe Modularisierung der Inhalte was eine hohe
Wiederverwendung erlaubt
Sehr hohe Eignung um Dokumentation für Software zu erstellen und anschließend im Web Format zu veröffentlichen
Die Fähigkeit einzelne Topics zu übersetzen da keine Inhaltsabhängigkeit besteht
Nachteile mit DITA:
Hohe Lernkurve um DITA meistern zu können
Hohe Kosten für die Migration von Daten
Die Erzeugung von Formatvorlagen ist komplizierter im Vergleich zu Docbook

Modul basierende DTD´s – S1000D, ATA and Shipdex

Es gibt eine weitere zusätzliche Alternative zur Docbook –und Topic basierenden DTD und das ist Aufgliederung der XML-Inhalte in kleinere Module. Diese Architektur unterscheidet sich vielleicht nicht so sehr von der „Topic DTD“ aber der Unterschied besteht in der Verlinkung der Module mir der Produktstruktur.
 
Alle drei Standards ähneln sich sehr aber sind Initiativen von verschiedenen Industriegruppen. S1000D – Militärindustrie, ATA – Kommerzielle Flugzeugindustrie und Shipdex – Schiffbauindustrie.

Es ist relativ einfach die Gründe für die Existenz dieser Standards zu verstehen. Wenn ein Flugzeughersteller die gesamte Dokumentation des Produktes zusammenfügen möchte, sind möglicherweise mehr als einhundert Zulieferer involviert. Wenn jeder Zulieferer sein eigenes Format und Standard benutzen würde, wäre es nahezu unmöglich die unterschiedlichen Informationsdatensätze zusammenzusetzen. Es kommt sogar vor,  dass Zulieferer welche denselben Standard benutzt haben Ihre Informationen im XML Format übergeben müssen, ohne dass der Inhalt mit Hilfe von Formatvorlagen (Stylesheets) formatiert wurde. All das um eine optimale Erstellung der Dokumentation zu gewährleisten.

Für die einzelnen Hersteller ist es sehr aufwendig den Standard S1000D, ATA oder Shipdex zu folgen. Demzufolge werden die Standards weniger oft außerhalb der oben genannten Industriebereiche und deren Projekten benutzt. Für Zuliefererunternehmen welche nur gelegentlich an Projekten beteiligt sind, ist es in einigen Fällen empfehlenswert einen anderen „einfacheren“ Standard zu benutzen und eine spezielle Exportfunktion erstellen zu lassen, um dann die Inhalte in die erforderliche Informationsstruktur des Industriestandards zu exportieren.

Zusammenfassung

Ein Standard ist immer ein Standard und als solcher versucht er allen Anforderungen gerecht zu werden. Das führt letztendlich dazu, dass fast alle Standards für viele Anwendungen „overengineered“ bzw. technisch überzüchtet und dadurch sehr schwierig zu benutzen sind. Hierzu das folgende Beispiel: In DITA gibt fünf verschiedene Möglichkeiten ein Bild zu markieren. Man kann sich vorstellen, dass Bilder dann nicht immer optimal markiert werden was zur Folge hat das die Wiederverwendung von bereits bestehenden Bildern darunter leidet. Aufgrund dieser Komplexität wird bei vielen Projekten eine zusätzliche Projektphase benötigt währenddessen dann der Standard an die Unternehmens –bzw. Projektbedürfnisse angepasst wird. Das ist meistens sehr aufwendig und verursacht zusätzliche Kosten.

Simonsoft hat „Techdoc“ entwickelt. „Techdoc“ ist unsere eigene Version einer book-basierenden DTD aber mit einigen Veränderungen. Dazu gehören bessere Prozessbeschreibungen, vorgefertigte Stylesheets bzw. Formatvorlagen und erhöhter Grad der möglichen Modularisierung. Außerdem ist es möglich mit Techdoc erstellte Inhalte in modularisierte Standards wie Shipdex oder S1000D zu exportieren.

Ziel der Entwicklung von Techdoc war es, eine unkomplizierte, flexible, preiswerte aber dennoch sehr leistungsfähige XML Autorenlösung für mittelständische Unternehmen anbieten zu können.      


Ihr Simonsoft Team