Projekte dokumentieren — mit AsciiDoc

• Du musst ein Projekt oder ein Programm dokumentieren?
• Bitte keine unterschiedlich alten Office-Dokumente auf den „Dokumentations-„Kompost mehr tun… du brauchst eine aktuelle Hilfe!?
• Ihr würdet auch gern eine Versionsverwaltung nutzen?

Was du dazu brauchst, ist eine Markup-Sprache!

Die gibt es wie Sand am Meer:
von den Urgesteinen troff und Groff über Dokumentations-Tools wie DocBook und reStructuredText oder Textsatz-Systemen wie LaTeX… oder aber der allgegenwärtige und hippe Star Markdown.

Hinweis:
All diese Markup-Sprachen sind konventionen oder Standards, um einfache Textdateien zu schreiben. Aus diesen werden später Webseiten, Dokumente oder PDF-Dateien generiert, die den „fertigen“ Text enthalten. Markdown beispielsweise liest und schreibt sich _sehr viel einfacher als LaTeX — hat aber auch einige Haken im Detail und wesentlich weniger Funktionen. Dafür brauchst du aber auch wesentlich weniger Vorwissen als für LaTeX.
Kurz: jede Markup-Sprache hat ihre eigenen Vor- und Nachteile.

AsciiDoc wurde speziell für Dokumentationen entwickelt und baut auf dem etablierten DocBook auf. Es bringt daher viele nützliche Funktionen für das Schreiben und Verweisen in Dokumentationen mit.
Natürlich sind die üblichen Überschriften, Tabellen, Bilder und Querverweise sind kein Problem. Auch Formeln lassen kannst du mit Asciimath oder LaTeX-Formeln setzen. Und: AsciiDoc bleibt immer gut lesbar — auch im Quellcode!

Hinweis:
Ascii ist die Abkürzung für „American Standard Code for Information Interchange“ und ist eine Zeichenkodierung.
AsciiDoc ist die standardisierte Markup-Sprache selbst.
AsciiDoctor das dazugehörige Programm, das Dokumente in andere Formate umwandelt.

Features, Features, Features…

Wichtig für Anleitungen sind aussagekräftige Kästen mit „Wichtig!“ oder „Info“. Daher gehören sie auch zum Standard-Repertoire (inklusive der passenden Beschriftung oder Symbole).
Eine große Stärke sind auch Tabellen, deren Zeilen sich für einfachere Lesbarkeit einfärben lassen. Features für Fortgeschrittene, wie etwa Zellen zusammenfassen und Spaltenbreiten festlegen, kannst du ebenfalls leicht umsetzen.
Und damit du die Features deines Projekts gut hervorheben kannst, musst du auch auf deine geliebten Checklisten nicht verzichten.

Unter-Dokumenten kannst du in AsciiDoc per include einbinden. Willst du beispielsweise eine bestimmte Warnung mehrmals im Dokument anzeigen, schreibst du sie nicht immer wieder; du schreibst sie in eine eigene Datei, die du mehrmals aufrufst.
Besonderer Leckerbissen für Programmierer*innen: auch Code-Listings und Schnipsel aus Quellcode lassen sich so direkt aus AsciiDoc heraus aufrufen: einfach auf die andere Datei mit dem Quellcode verweisen — so einfach kann das sein!
Mit Attributen (z.B. einer Versionsnummer) kannst du kleinere Texte ebenfalls merhmals an anderen Stellen benutzen. Auch das ist nicht nur für Schreibfaule, sondern beugt Wiederholungsfehlern vor.

Mit AsciiDoc geht aber noch mehr:
Tastenkombinationen für die Bedienung von Programmen kannst du damit ebenfalls darstellen. Sogar Wenn-Dann Abfragen bei der Dokumentenerstellung sind möglich (wenn etwa eine Information nur nützlich für ein bestimmtes Ausgabeformat ist). Ein Video ergibt auf einer Webseite nämlich mehr Sinn als in einer PDF…