Projekte dokumentieren — mit AsciiDoc

Screenshot des Asciidoc-Artikels im Texteditor (links) und als HTML-Seite (rechts)
Mit der flexiblen Markup-Sprache AsciiDoc kannst du komplexe technische Dokumentation in schlichte aber lesbare Textdateien schreiben. Viele nützliche Funktionen helfen dir dabei.
  • 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…

Außerdem kannst du Diagramme mit Mermaid oder PlantUML ebenfalls direkt in deine Dokumente einbetten.

Ach und übrigens:
Neben HTML-Dateien lässt sich AsciiDoc auch als DocBook, Man page, PDF, EPUB oder Präsentation mit reveal.js ausgeben.
Die Vorlagen für alle Formate lassen sich dabei anpassen. Sogar wissenschaftliche Texte kannst du damit schreiben, denn mit Erweiterungen unterstützt AsciiDoc auch BibTeX-Dateien, die deine Quellen enthalten.

Dokumentation als Code

Du siehst: 1000 Nützlichkeiten um deine Dokumentation konsistent und aktuell zu halten. Hilfreich ist dabei auch, dass sich AsciiDoc-Dateien (weil sie schlichte Textdateien sind) perfekt mit einer Versionsverwaltung wie z.B. Git verwalten lassen. Damit könnt ihr auch im Team arbeiten und seid direkt bei den Programmierer*innen, die die Software schreiben.

AsciiDoc eignet sich bestens, um aus einfachen Textdateien später umfangreiche Dokumente zu erzeugen — egal ob Webseite, Buch oder Präsentation. Viele tolle Funktionen helfen dir dabei, Fehler zu vermeiden und komplexe Anforderungen umzusetzen. Dabei bleibt AsciiDoc immer lesbar — egal ob im Quellcode oder als Dokument.
Wenn du also ein “Mittelding” aus LaTeX und Markdown suchst, könnte AsciiDoc genau das richtige sein.

Fun-Fact:

Dieser Beitrag wurde extra in AsciiDoc geschrieben — nur so als Test.

https://asciidoc.org/

Hilfe

Videos


Creative Commons Lizenzvertrag
Dieses Werk ist lizenziert unter einer Creative Commons Namensnennung – Weitergabe unter gleichen Bedingungen 4.0 International Lizenz.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert