Treat your documents like code
Präsentationen und Dokumentationen zu erstellen ist nicht immer ein leichtes Thema. Mit diesem Beitrag möchte ich meine Erfahrungen teilen und zeigen, wie ich aktuell meine Dokumentationen und Präsentationen erstelle. Mittlerweile behandle ich meine Dokumentationen wie meinen Code und schreibe diese in Asciidoc – revisioniert via Git.
Um die Grundprobleme zu verstehen möchte ich erst einmal darauf eingehen, welche Anforderungen meist an Dokumentationen innerhalb von Projekten bestehen.
- In großen Projekten werden Teilbereiche meist durch unterschiedliche Kollegen realisiert. Diese erstellen die Dokumentation für Ihren Teilbereich, der jedoch später in einer Gesamtdokumentation zusammen laufen sollte.
- Kollegen sollten sich nicht gegenseitig blockieren und auch gleichzeitig am Dokument arbeiten können, möglichst ohne den Aufwand, die Arbeiten später wieder zusammenzuführen.
- Der Kunde möchte in der Regel über den aktuellen Stand der Dokumentation informiert sein. Eventuelles Feedback sollte natürlich in das Dokument einfließen.
- Dahingehend wird auch eine komplette Änderungshistorie benötigt.
- Um möglichst jeden Kunden glücklich zu machen sollte das Zielformat flexibel bleiben.
Meist werden Dokumentationen aber einfach in Microsoft Office oder einem vergleichbarem Tool erstellt. Welche Probleme ergeben sich dadurch?
- Durch das Format ist man an ein proprietäres Tool gebunden.
- Durch zusätzlichen Verschiedene Versionen (die auch tatsächlich noch bei Kunden im Einsatz sind), wird die Zusammenarbeit zusätzlich erschwert (2003, 2007, 2010, 2013, LibreOffice)
- Die Speicherung des Dokuments wird meist auf einem zentralen CIFS-Share durchgeführt. Durch das Filelocking ist es nicht möglich das mehrere Personen das Dokument gleichzeitig bearbeiten.
- Durch diese Tatsache werden meist Teildokumente erstellt, die später manuell zusammengeführt werden.
- Vorabversionen werden meist manuell per E-Mail an den Kunden gesendet.
- Korrekturvorschläge und Verbesserungen werden in der Vorabversion farblich markiert und müssen im Nachgang wieder manuell in das Hauptdokument eingearbeitet werden.
- Eine wirkliche Änderungshistorie existiert meist gar nicht.
Ich erstelle meine Dokumentationen in dem rein textbasierten Format Asciidoc in Verbindung mit einer Revisionierung mit Git. Bearbeitet werden bei mir nur noch die Daten bzw. der tatsächliche Inhalt, nicht das tatsächliche Zielformat.
Der Ansatz ist sicherlich nicht neu – und viele werden bereits von LaTeX oder Docbook gehört haben. Der große Vorteil in Asciidoc liegt jedoch in der einfachen Syntax, die anders als XML basierte Alternativen, auch im Quellformat lesbar bleibt. Der Syntax ist etwas an Markdown angelehnt, bietet jedoch deutlich mehr Funktionen, die bei größeren Dokumenten sehr hilfreich sein könnten. Als Beispiel seien hier eine Include Funktion (zur Aufteilung von großen Dokumenten in einzelne Dateien) oder ein automatisch generiertes Inhaltsverzeichnis genannt. Hier beispielhaftes ein kleines Dokument in Asciidoc.
= Titel des Dokuments Simon Lauger <author@example.com> == Überschrift H1 === Überschrift H2 Normaler Text * Listenpunkt 1 * Listenpunkt 2 *Fetter Text*, _kursiver Text_, ...
Mögliche Ausgabeformate sind unter anderem HTML5, PDF, Docbook oder Präsentationen via deck.js. Das Design kann für jedes Format via CSS komplett an die eigenen Bedürfnisse angepasst werden. Durch die komplette Trennung von Design und Content ist es später ein leichtes etwa ein neues Firmenlogo in alle vorhandenen Dokumente zu integrieren.
Um den Text von Asciidoc nach HTML5 zu konvertieren genügt ein einfacher Befehl. Asciidoctor basiert auf Ruby und kann meist direkt über den verfügbaren Paketmanager oder rubygems.org installiert werden.
asciidoctor example.adoc
Das anschließende Resultat sieht wie folgt aus.
Beispielausgabe von Asciidoctor in HTML5
Durch das Zusammenspiel des rein textbasierten Quellformates in Verbindung mit Git ergeben sich folgende Vorteile.
- Komplette Versionsverwaltung mit allen weiteren Vorteilen von Git (z.B. Branches, Versionstags usw.).
- Jeder Kollege kann seinen Teil der Dokumentation Offline bearbeiten und später in das zentrale Repository pushen.
- Bei Bedarf können Git Mechanismen genutzt werden um Konflikte bei einem Merge zu beheben.
- Dem Kunden kann auf Wunsch direkt Zugriff auf das Repository gegeben werden. Verbesserungsvorschläge können via Pull-Requests vorgeschlagen werden.
- Die Vorschau der fertigen Dokumentation wird meist sogar in der GUI des Git-Servers angezeigt (Bitbucket, GitLab, GitHub).
Für Entwickler entfällt zudem der lästige und zeitaufwändige Wechsel zwischen Entwicklungsumgebung (IDE) und Office Programm. Das sorgt dafür das Änderungen ohne viel Aufwand schnell „nachdokumentiert“ werden können. Einfache Texteditoren haben zudem den Vorteil das man sich auf das wesentliche (den Content) konzentrieren kann, statt von den vielen, teils unnötigen Features und Farben, erschlagen zu werden.
Viele IDEs und Editoren (etwa Atom oder IntelliJ) bieten zudem eine komplette Live Preview auf das fertige Dokument.
Hier noch einige relevante Links für den ersten Schritte mit Asciidoctor.
Wie sich die Dokumentation via Asciidoctor sauber in einen Entwicklungsworkflow integrieren lassen zeige ich in einem nachfolgendem Beitrag.
