Beirat Online-Events: Docs as Code kann auch PDF – eine praxisnahe Einführung in AsciiDoc

Mehr als 100 Teilnehmende nutzten die Mittagspause, um einen Einstieg in AsciiDoc zu erhalten. 

Referent Alexander Schwartz (IBM), der als ehemaliges Mitglied der AsciiDoc Working Group über umfassende Praxiserfahrung verfügt, führte anschaulich in AsciiDoc ein und zeigte auf, welche Auszeichnungen und Medien in einem PDF verwendet werden können. Dabei betonte er auch die Rolle des eigentlichen Prozessors „Asciidoctor“, der die Konvertierung im Hintergrund übernimmt. Er erklärte, dass alles, was DocBook kann, auch mit AsciiDoc möglich ist. Es gibt dafür zwar keine direkte Mapping-Tabelle, aber in der ausführlichen Anleitung zu AsciiDoc findet man die Lösungen. 

Folgende Mehrwerte/Vorteile sieht er für den Docs-as-Code-Ansatz, umgesetzt mit AsciiDoc: 

• Layout und Inhalt sind getrennt. 
• Inhalte können wiederverwendet werden. 
• Diagramme können als Text erstellt werden. Damit sind Änderungen einfach und ohne Zeichenprogramm möglich. Zudem erhält man dadurch auch für Diagramme eine Änderungshistorie durch Git. 
• Versionierung kann in einem Versionierungstool wie GitHub erfolgen. 
• Verwendbar mit allen Betriebssystemen. 
• Andere PDFs können direkt eingebunden werden. 
• PDF-Erzeugung lässt sich gut automatisieren. 
• Aus derselben Quelle können parallel weitere Formate wie HTML oder EPUB generiert werden. (Single Sourcing) 

Der Einstieg in AsciiDoc 

Um den Einstieg zu erleichtern, empfahl Alexander Schwartz eine klare Arbeitsteilung. Insbesondere beim initialen Aufsetzen des Prozesses sei die Zusammenarbeit mit anderen Fachbereichen sinnvoll: Softwareentwickler:innen können die automatisierte Build-Pipeline einrichten, während CSS-Expert:innen das Layout für die PDF- und HTML-Ausgabe gestalten. So kann sich das Redaktionsteam voll auf seine Kernkompetenz, die Erstellung der Inhalte, konzentrieren. 

Redaktionelle Themen im Fokus 

Für die Teilnehmenden waren besonders die redaktionellen Anwendungsmöglichkeiten von großem Interesse. Der aktive Austausch im Chat zeigte, dass viele Fragen aus dem klassischen Redaktionsalltag kamen.  

So wurden beispielsweise Detailfragen zur typografischen Kontrolle, etwa zur Vermeidung von Schusterjungen und zur Absatzkontrolle in der PDF-Ausgabe, direkt beantwortet. Auch die Einbettung von Codebeispielen für API-Dokumentationen, inklusive der Möglichkeit, bestimmte Zeichen oder Wörter hervorzuheben, wurden diskutiert.  

Besonders thematisiert wurde die Möglichkeit, über include-Anweisungen Inhalte aus anderen Dateien wiederzuverwenden. 

Diagrammerstellung aus Text 

Ein weiteres Highlight war die Erstellung von Diagrammen direkt aus Text. Am Beispiel von PlantUML wurde gezeigt, wie daraus beim Generieren des Dokuments statische Grafiken erzeugt werden.  

Im Chat kam zudem die populäre Alternative Mermaid.js zur Sprache. Hier wurde ein spannender technischer Unterschied für HTML-Webseiten erklärt: Während PlantUML-Diagramme serverseitig als feste Bilddateien generiert werden (und daher statisch als Bilder ausgeliefert werden), rendert Mermaid.js standardmäßig den beschreibenden Code erst live und dynamisch im Webbrowser des Endnutzers. 

IntelliJ AsciiDoc Plugin 

Ein zentraler Punkt in der Praxisvorführung war die Arbeitserleichterung durch das gezeigte IntelliJ AsciiDoc Plugin: https://intellij-asciidoc-plugin.ahus1.de/. Praktisch: Ähnlich wie bei der Eingabe von Formeln in Excel schlug das Werkzeug nach der Eingabe der ersten Buchstaben passende AsciiDoc-Syntax vor (Autovervollständigung). Häufig genutzte Syntax ist zudem über eine Menüleiste schnell verfügbar. Als äußerst hilfreich empfanden viele Teilnehmende auch die durch das Plugin im Editor verfügbare Live-Vorschau. In einer geteilten Ansicht war der formatierte Text direkt neben dem Quellcode zu sehen, sodass das Ergebnis der Arbeit unmittelbar überprüft werden kann.  

Der Weg zum PDF: Zwei Ansätze für unterschiedliche Anforderungen 

Wie der Titel der Veranstaltung versprach, lag ein besonderer Fokus auf der Frage, wie aus einfachen Textdateien professionelle PDF-Dokumente generiert werden können. Alexander Schwartz demonstrierte hierzu zwei etablierte, auf dem Werkzeug Asciidoctor basierende Methoden, die unterschiedliche Projektanforderungen abdecken: 

• Der Standardweg mit asciidoctor-pdf: Für die schnelle und zuverlässige Erstellung von qualitativ hochwertigen PDFs ist dieses Werkzeug die erste Wahl. Das Layout und Design lassen sich dabei über zentrale Theme-Dateien (im YAML-Format) steuern und so unkompliziert an das eigene Corporate Design anpassen. 
• Der flexible Weg mit asciidoctor-web-pdf: Wenn maximale gestalterische Freiheit benötigt wird, kommt dieser zweite Ansatz zum Tragen. Hierbei wird der Inhalt zunächst in eine HTML-Datei umgewandelt. Anschließend wird diese mithilfe von modernen Web-Technologien (CSS) präzise gestaltet und in ein PDF überführt. Diese Methode erlaubt komplexe, pixelgenaue Layouts, wie man sie aus klassischen DTP-Programmen kennt.  

AsciiDoc vs. XML 

In der anschließenden Diskussionsrunde wurde u.a. die strategische Einordnung von AsciiDoc im Vergleich zu XML-basierten Redaktionssystemen thematisiert. Ein Teilnehmer merkte kritisch an, dass AsciiDoc im Gegensatz zu XML keine strikte, systemseitig validierte Strukturkontrolle (wie das ID/IDREF-Konzept) bietet. Alexander Schwartz entgegnete, dass der AsciiDoc-Workflow hier auf eine andere Philosophie setzt: Statt auf starre, systemerzwungene Validierungen baut der Ansatz auf klare Konventionen, modulare include-Strukturen und unterstützende Werkzeuge wie Antora. Eine ID kann in AsciiDoc zudem durch einen Anker (anchor) und IDREF durch eine Crossreferenz (xref) umgesetzt werden. Britta Görs, Beirat Online-Events, brachte es auf dem Punkt: In der Technischen Redaktion gilt es zunächst zu entscheiden, welche Anforderungen wir an das Ausgabemedium haben, und dann die Werkzeuge entsprechend zu wählen. Beide Wege haben ihre Berechtigung und sind für unterschiedliche Einsatzszenarien gedacht. 

Weiterführende Links

• AsciiDoc: https://asciidoc.org 
• Asciidoctor: https://asciidoctor.org 
• IntelliJ AsciiDoc Plugin: https://ahus1.de/post/technical-writing-udemy 
• PlantUML: http://plantuml.com/https://real-world-plantuml.com/ 
• docToolchain: https://doctoolchain.github.io/docToolchain/ 
• Asciidoctor PDF: https://docs.asciidoctor.org/pdf-converter/latest/ 
• Asciidoctor Web PDF: https://github.com/ggrossetie/asciidoctor-web-pdf 
• Docker Container mit Asciidoctor & Co. https://github.com/asciidoctor/docker-asciidoctor/ 
• Documentation as Code mit Asciidoctor: https://heise.de/-4642013 
• Kurs von Alexander Schwartz auf Udemy (englische Sprache): Technical Writing with AsciiDoc and IntelliJ IDEA 
• Schritt-für-Schritt-Anleitung zum Selbststudium: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/technical-writing/