DocBook: Clever dokumentieren

Die Dokumentation von Software ist eine Aufgabe, die den wenigsten Leuten Spass macht. Und die mit dem falschen Werkzeug endgültig zur Qual wird – unter Umständen auch für den Leser, wenn beispielsweise Referenzen fehlen oder unhandliche Formate zur Verfügung stehen.

Neben dem inhaltlichen Aspekt beeinflussen etliche weitere Kriterien die Qualität einer Dokumentation. Als Leser wünscht man sich verschiedene Formate wie HTML oder PDF, aus denen man dasjenige auswählen kann, das der eigenen Arbeitsweise am meisten entgegenkommt. Dazu sollte man sich gut durch das Dokument navigieren können, damit man schnell zu den gesuchten Informationen gelangt.
Für die Autoren ist es nicht nur wichtig, die Anforderungen der Leser zu erfüllen, sondern die Dokumente auch einfach und plattformunabhängig editieren zu können. Dazu gehört auch, dass sich verschiedene Revisionen problemlos vergleichen lassen, beispielsweise mit GNU diff oder der Versionskontrolle der Wahl, und dass man – was bei der Arbeit im Team wichtig ist – gleichzeitig an verschiedenen Stellen im Dokument arbeiten kann. Ausserdem sollten sich viele bibliographische Elemente wie Inhaltsverzeichnisse einfach erzeugen lassen und programmseitig für ein einheitliches Aussehen der Dokumentation gesorgt werden.