Die wichtigste der Dokumentationspraktiken ist, dass eine verfasst wird! Zuviele Programmierer lassen dies gänzlich aus. Aber es gibt zwei gute Gründe, die dafür sprechen:
Die Dokumentation kann als Entwurfsdokument dienen. Der beste Zeitpunkt, um eine zu verfassen, liegt noch bevor der Eingabe einer einzigen Zeile Code; man erarbeitet erstmals das Konzept der Funktionalität und deren Umsetzung. Es wird dir nicht entgehen, dass der Prozess der Umschreibung der erwünschten Funktionalität deines Problems und deren Umsetzung in natürlicher Sprache, deinen Geist auf jene Fragen fokussieren wird. Dies wird dir unter Umständen eine ungeheures Volumen an späterer Revidierung ersparen.
Die Dokumentation ist zugleich ein Repräsentant der Qualität deines Code. Viele Personen interpretieren dürftige, unzureichende oder fehlerhafte Dokumentation für ein Programm, als ein Indiz, dass der Programmierer vernachlässigend oder gleichgültig betreffend den Bedürfnissen des Endbenützers agiert. Eine umfassende Dokumentierung, auf der anderen Seite hinterlässt einen Eindruck von Intelligenz und Professionalität. Wenn sich dein Programm mit anderen zu messen hat vergewissere dich, dass deine Dokumentation qualitativ zumindest so gut wie die ihrigen ist; sofern sie potentiell schlechter sein sollte, werden die Endbenützer deine Software ohne ein zweiten Blick verwerfen.
Dieses HOWTO ist nicht der Platz für einen Kurs betreffend technischen Schreibens, selbst wenn es praktikablen Nutzen hätte. Also werden wir uns primär auf die verfügbaren Formate und Programme für die Erstellung und die Konvertierungen von Dokumentationen fokussieren.
Obschon Unix und die Open-Source Gemeinschaft eine lange Tradition von mächtigen Dokumentformattierungs Programmen miteinander teilen, bewirkte die Überfülle an verschiedenen Formaten, dass Dokumentationen tendenziell fragmentiert waren und es sich als ungemein schwierig für Endbenützer erwies, in einem zusammenhängendem Kontext den Inhalt zu durchforschen oder indexieren. Wir werden die Gebrauchspraktiken, Stärken wie auch Schwächen der gängigen Dokumentationsformate zusammenfassen. Dann werden wir weiterhin einige Ratschläge betreffend empfehlenswerten Praktiken erteilen.
Nun werden wir die Dokumentbeschreibungsformate, welche heutzutage weitverbreitet unter Open-Source Entwicklern ihren Anklang finden ausführlicher erläutern. Wenn wir von "Präsentations" Beschreibung sprechen, so referenzieren wir explizit auf die Beschreibung des Erscheinungsbildes des Dokumentes (wie z.B. ein Schriftwechsel). Wenn wir von "struktureller" Beschreibung sprechen, dann referenzieren wir auf die Beschreibung, die die logische Struktur des Dokuments umschreibt (wie z.B. ein Sektionsende oder eine Hervorhebungsmarkierung). Und wenn wir von der "Indexierung" sprechen, beinhaltet dies den Prozess der Extrahierung von Dokumenten, die einem gewissen Suchwort oder Titel-/Kategoriebezeichnern entsprechen, welche Endbenützer verwenden können, um zuverlässig Material von Interesse innerhalb der ganzen Kollektion zu orten.
Das überaus gängigste Format (von Unix geerbt) ist eine primitive Form der Präsentationsbeschreibungsprache. Der Befehl man(1) stellt einen Seitenindexierer wie auch eine steinzeitlich anmutende Suchfunktion dem Benützer zur Seite. Bilder, Hyperlinks und Indexierung werden nicht unterstützt. Lässt sich vergleichsweise gut zu Postscript für Druckzwecke konvertieren. Lässt sich nur schlecht in HTML umwandeln (nur als unformattierter Text). Programme, um Manualseiten zu interpretieren sind auf allen Linux Systemen und Invarianten vorinstalliert.
Das Manualseiten Format ist nicht schlecht für die Zusammenfassung von Befehlen oder Dokumenten, die Kurzreferenzen beinhalten, die dem erfahrenen Benützer z.B. betreffend den möglichen Optionen auf die Sprünge helfen. Es beginnt unter der Dokumentierung eines Programms mit komplexen Schnittstellen und vielen Optionen zu leiden und kollapsiert gänzlich, wenn man einen Satz von Dokumenten mit Kreuzreferenzen zu "pflegen" beabsichtigt (die Beschreibungssprache beeinhaltet nur eine schwache Unterstützung für Hyperlinks, welche normalerweise nicht verwendet werden).
In erhöhendem Masse sich zum Standard entwickelnd seit sich das Web in 1993-1994 rapide auszubreiten begann. Die Dokumentbeschreibungssprache ist teilweise strukturell, grösstenteils jedoch präsentations-ausgerichtet. Durch jegliche Arten von Webbrowser einsehbar. Gute Implementierung von Bilder und Hyperlinks. Eingeschränkt Möglichkeiten zur Indexierung vorhanden, gute Indexierungs- und Suchmaschinen Technologien existieren jedoch und sind weitverbreitet vorhanden. Lässt sich überaus gut in das Postscript Format für Druckzwecke konvertieren. HTML Programme sind nun universell verfügbar.
HTML ist sehr flexibel und für viele Formen von Dokumentationen geeignet. Bedauerlicherweise ist es zu flexibel; wie auch beim Manualseiten Format erschwert sich die automatische Indexierung, da eine Fülle der Beschreibung sich vielmehr dem visuellen als dem strukturellen Aspekt des Dokumentes widmet.
Texinfo ist das durch die Free Software Foundation verwendete Dokumentationsformat. Es ist ein Bund von Makros, die der mächtigen TeX Formattierungsverarbeitung aufgesetzt wird. Grösstenteils strukturell, teilweise präsentations-ausgerichtet. Durch Emacs oder ein alleiniges info Programm einsehbar. Gute Unterstützung von Hyperlinks, keine für Bilder. Beinhaltet sowohl für Druck- wie auch Onlinezwecke treffende Indexierungsmöglichkeiten; wenn man ein Texinfo Dokument installiert, wird dem Dokument automatisch ein Verweis zu einer Verzeichnisauflistung aller auf dem System verfügbaren Texinfo Dokumente hinzugefügt. Lässt sich hervorragend nach Postscript und gebrauchbares HTML konvertieren. Texinfo Programme sind auf den meisten Linux Systemen vorinstalliert; sie sind zudem auch über die Free Software Foundation Website erhältlich.
Texinfo beinhaltet gute Entwurfsmöglichkeiten; es ist ziemlich nützlich um Bücher "roh" zu verfassen wie auch für kleinere On-line Dokumente; aber ebenso wie HTML, hat es gewisse amphibische Charakterzüge -- die Dokumentbeschreibung ist teilweise struktureller Natur, andere Elemente sind wiederum präsentationsfokussiert; letztere können jedoch Probleme bei der Konversion zu anderen Dateiformaten erzeugen.
DocBook repräsentiert eine umfangreiche, wohl durchdachte Dokumentbeschreibungssprache, die auf SGML (unlängst erschiene Versionen jedoch auf XML) basiert. Im Gegensatz zu all den anderen hier erläuterten Formaten ist gänzlich struktureller Natur, ohne die Möglichkeit Einfluss auf die visuelle Formatierungen zu nehmen. Ausgezeichnete Unterstützung für Bilder und Hyperlinks. Gute Indexierungsmöglichkeiten. Lässt sich mit annehmbarem Ergebnis nach HTML konvertieren und mit akzeptablen Resultat nach Postscript für Druckzwecke (die Qualität nimmt in dem Masse zu wie die obig erwähnten Programme weiterentwickelt werden). Programme wie auch Dokumente sind über die DocBook Website erhältlich.
DocBook ist hervorragend für umfangreiche, komplexe Dokumente geeignet; es wurde mit der spezifischen Absicht entworfen, technische Handbücher zu unterstützen und die Konversion in mehrere Ausgabeformate zu ermöglichen. Einige der Nachteile mögen die Komplexität sein, ein nicht gänzlich ausgereiftes (obschon sich verbesserendes) Toolset und einführende Dokumentationen, welche unverständlich und oftmals stark verworren sind.
In Juli 2000 haben sich "Repräsentanten" verschiedenster wichtiger Open-Source Projektgruppen zu einer Gipfelkonferenz in Monterey, California eingefunden (u.a. die GNOME & KDE Gruppen, die Free Software Foundation, das Linux Dokumentationsprojekt wie auch die Open Source Initiative). Ein Bestreben des Gipfels war gängige Dokumentationspraktiken wie auch -Formate, um den Datenaustausch zu erleichern, zu etablieren, sodass der Nährboden für sehr viel umfangreichere und vereinheitlichte Dokumentationen evolvieren kann.
Konkret ausgedrückt wurde von allen im Konsensus die Idee erarbeitet eine Art von Dokumentationspacket zu unterstützen, welches wenn es auf einem System installiert werden sollte, sich unverzüglich in einen umfassenden, systemweiten Index von Dokumenten integriert - in der Weise, dass jener später über eine universelle Schnittstelle eingesehen werden kann wie auch Suchfunktionen durchgeführt werden können. Von der Annäherung, die das GNOME und KDE Projekt bezüglich dieser wünschenswerten Entwicklung bereits getätigt haben, war klar ersichtlich, dass es vielmehr eine strukturelle Sprache als eine, die den visuellen Inhalt beschreibt, erfordern wird.
Die Konferenz hiess eine Entwicklung gut, die schon seit längerer Zeit absehbar gewesen war; Schlüsselprojekte der Open-Source Gemeinschaft befinden sich im Prozess zur Migration (oder haben jene bereits vollzogen) ihrer Dokumentationen auf das DocBook Format und berufen es gleichzeitig zum Standard.
Die Teilnehmer waren sich ebenso einig, dass das `Dublin core' Metadaten Format (ein internationaler Standard der durch Bibliothekare mit einem - Auge für die Indexierung von digitalem Material - entworfen wurde) weiterhin für Dokumentindexierungen verwendet werden sollte; genaure Einzelheiten dieses Vorgehens sind noch immer in der Ausarbeitung und werden wahrscheinlich in einigen Ergänzungen zu der DocBook Beschreibungssprache, um zusätzlich eingebette Dublin Core Metadaten zu unterstützen, resultieren.
Die Entwicklung ist klar: eine häufigere Verwendung von DocBook mit zusätzlichen Standards, welche die automatische Indexierung von Docbook Dokumenten aufgrund ihren Index Tags und Dublin core Metadaten unterstützen werden. Gewisse Detailarbeit muss sicherlich noch erarbeitet werden, aber dieser Prozess ist bereits im gange. Die älteren präsentations-basierten Beschreibungssprachen' Tage gehören der Vergangenheit an. (Dieses HOWTO wurde dem DocBook in August 2000 hinzugefügt.)
Folgendermassen werden Personen, die neue Open-Source Projekte ins Leben rufen werden, der Entwicklung vorrauseilen und sich absehbar viel Aufwand ersparen durch allfällige, spätere mühselige Konvertierungen, sofern sie bereits jetzt DocBook als ihr Hauptformat benutzen sollten.