DocBook: Clever dokumentieren

DocBook: Clever dokumentieren

25. Mai 2007 - Bücher, Dokumentationen – dies ist das Metier der XML-Anwendung DocBook, die Verlage sogar als Quellformat für ihre Bücher verwenden.
Artikel erschienen in IT Magazine 2007/10

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.


Viele Kriterien

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.

 
Seite 1 von 5

Neuen Kommentar erfassen

Anti-Spam-Frage Wieviele Zwerge traf Schneewittchen im Wald?
Antwort
Name
E-Mail
GOLD SPONSOREN
SPONSOREN & PARTNER