Was ist DocBook?

Dokumentation mit DocBook

Dass ein Benutzerhandbuch verständlich geschrieben sein sollte, versteht sich von selbst (auch, wenn massenhaft unbrauchbare Produktheftchen das Gegenteil vermuten lassen). Alleine ein verständlicher Schreibstil genügt jedoch nicht, eine nachhaltige Dokumentation zu erstellen.

Nachhaltigkeit in der technischen Dokumentation bedeutet:

  • Anwendung offener und allgemein akzeptierter Standards.
  • Herstellerunabhängiges Dokumentationssystem.
  • Redaktionelle Pflege ohne hohen Aufwand.
  • Hohe Flexibilität bei Einbindung externer Quellen (GUI-Elemente, Datenbanken).
  • Skalierbare Zusammenstellung eigenständiger Dokumentationselemente.
  • Gestaltete Veröffentlichung über verschiedene Medien (print, online) auf Basis desselben Textes.
  • Niedrige Portierungskosten bei Wechsel des Dienstleisters oder Umstellung des Dokumentationssystems.
  • Unkomplizierte Koordination von Übersetzungen.

Eine elegante Möglichkeit, all das unter einen Hut zu bringen, bietet DocBook.

Was ist DocBook?

Bei DocBook handelt es sich um ein spezielles XML-Format, das das DocBook Technical Committee der Organization for the Advancement of Structured Information Standards (OASIS) eigens für die Erstellung technischer Dokumentationen bereits seit 1991 weiterentwickelt. Die mehr als 300 Auszeichnungselemente und etwa 70 Attribute der DocBook-XML lassen kaum Wünsche offen, was Formatierung und Struktur eines Handbuches angehen.

XML-typisch trennt DocBook den Inhalt von der Form: So legen Sie beispielsweise zunächst allgemein per DocBook-Auszeichnung fest, dass ein Textelement optisch hervorgehoben ist. Erst später bei der Textausgabe entscheiden Sie, welche Formatierung Sie medienabhängig verwenden wollen (z. B. unterstrichen im gedruckten Handbuch, kursiv oder innerhalb von „Anführungszeichen“ in der Online-Hilfe).

Sogenannte Transformationsregeln und -prozessoren steuern anschließend die Ausgabe des DocBook-Quelltextes unter anderem in PDF- oder HTML-Dokumente.

Die Verwendung sogenannter Entities steigert die Flexibilität der Dokumentation. Entities sind Variablen im Quelltext, die die Transformation im Zielformat ersetzt. So können Sie beispielsweise in der gesamten Dokumentation die Entity &produkt; verwenden. Erhält das Produkt auf Grund eines neuen Features auch eine neue Bezeichnung (oder erhält ein OEM-Kunde ein auf seine Produkte zugeschnittene Dokumentation), tauschen Sie einfach den mit der Entity festgelegten Namen aus, erweitern die Dokumentation um die Beschreibung des neuen Features und generieren die neue Dokumentation mit der neuen Produktbezeichnung.

Darüber hinaus besitzt die DocBook-XML noch viele weitere Vorzüge, die die Dokumentationserstellung effizienter gestalten.

Was ist DocBook nicht?

Wer aufwändige Layouts gestalten muss oder eine ausgefeilte Typografie in seinen Dokumenten verwendet, der ist mit einer DTP-Software eindeutig besser bedient. Kurz gehaltene Beileger, auf die notwendigsten Informationen reduziert, sind ebenfalls eher ungeeignet, da die Umwandlung in ein gefälliges Layout nicht trivial ist.

Wer jedoch viele Produkte mit einer (vielleicht sogar in weiten Teilen identischen) Dokumentation verwalten muss, für den ist ein Einsatz von DocBook durchaus ein lohnenswerter Ansatz.