Blog Docbook - Dokumentieren kann auch Spaß machen

Docbook - Dokumentieren kann auch Spaß machen

Welcher Entwickler kennt das nicht: Analyse, Architektur, Implementierung, Testen und meist nachher noch schnell alles dokumentieren. Arbeitsalltag eines Softwareentwicklers, von dem heutzutage weit mehr gefordert wird als Inselwissen. Gut aufgestellt zu sein in einem interdisziplinären Aufgabengebiet erfordert Organisation und passende Werkzeuge. Für die meisten Aufgaben hat man sich mittlerweile eine gute Entwicklungsumgebung mit den entsprechenden Plugins, eine Testsuite und vielleicht ein Modellierungswerkzeug zurechtgelegt. Die Dokumentation: Naja, die wird am Ende meist aus zeitlichen Gründen mehr oder minder vollständig in ein Textverarbeitungsprogramm gepresst. Idealerweise sollte jedoch auch das Dokumentieren ständiger Bestandteil eines kontinuierlichen Entwicklungsprozesses sein. Die Verwendung der üblichen Textverarbeitungsprogramme mag für Geschäftsbriefe und andere Dokumente geringen Ausmaßes erste Wahl sein. Wer jedoch schon mal versucht hat damit eine 500 Seiten lange Softwaredokumentation zu bearbeiten, verschiedene Bearbeitungsstände zu versionieren oder lediglich das Dokument mit all seinen Grafiken an einen Drucker zu senden, der wünscht sich schnell ein passenderes Werkzeug dafür.

Glücklicherweise haben sich schon Anfang der 90er Jahre einige schlaue Köpfe zusammengesetzt und Docbook ins Leben gerufen. Das mittlerweile von der OASIS (Organization for the Advancement of Structured Information Standards) kontinuierlich weiterentwickelte und frei erhältliche Dokumentationssystem ist besonders für die Dokumentation technischer Inhalte sowohl im Hard- als auch im Softwarebereich sehr gut geeignet.

Docbook macht im Vergleich zu den üblicherweise verwendeten WYSIWYG-Werkzeugen (What You See Is What You Get) erst einmal alles anders. Es vollzieht eine klare Trennung von Inhalt und Gestaltung des Dokumentes. Eine einmal gestaltete Vorlage wird vom Endanwender nicht mehr bearbeitet, das Coporate Design und die Durchgängigkeit in der Gestaltung des Dokumentes bleiben somit erhalten. Was für den Anwender zuerst etwas ungewöhnlich erscheint, bietet jedoch ziemlich schnell klare Vorteile. Er kann sich jederzeit auf das Wesentliche (den Inhalt) konzentrieren und braucht sich keine Gedanken mehr über jegliche Form der Gestaltung zu machen. Den meisten Entwicklern wird dies sehr entgegenkommen.

Die im Mittelpunkt des Systems stehende Trennung von Gestaltung und Inhalt basiert auf der Verwendung des XML-Formates, in dem sowohl Inhalt als auch die logische Dokumentenstruktur (Kapitel, Absätze, Abbildungen etc.) definiert sind. Sämtliche Definitionen der Gestaltungselemente werden erst im Prozess der Umwandlung in das gewünschte Ausgabeformat verarbeitet. Dies geschieht größtenteils über jeweils eine XSL-Datei (Extensible Stylesheet Language) pro Ausgabeformat. Diese XSL-Dateien sind integraler Bestandteil des Docbook-Systems und können selbstverständlich individuell angepasst werden.

Docbook beherrscht mehrere Ausgabeformate, wie z.B. html, epub, pdf und rtf. Beim Build-Prozess können somit aus einem einzigen Docbook-Projekt ohne Mehraufwände mehrere Formate zuverlässig generiert werden. Da die Quelldatei(en) mit jedem Text-Editor lesbar und editierbar sind, ergibt sich hieraus noch ein anderer, nicht zu vernachlässigender Vorteil: Die ganze Dokumentation ist versionierbar (beispielsweise über Werkzeuge wie SVN oder GIT) und somit kontrollierbarer und besser nachzuvollziehen. In der Praxis bedeutet dies meist einen deutlichen Zeitgewinn.

n-design hat Docbook erfolgreich in seinen Entwicklungsprozess aufgenommen. Der alltägliche Umgang mit dem Dokumentationssystem, positive wie auch negative Erfahrungen der Anwender und Beispiele zur Integration folgen bald an dieser Stelle.