Wir zeigen Ihnen in dieser Folge, wie Sie statische Websites mithilfe von AsciiDoc erstellen und pflegen können. Dazu greifen wir etwas tiefer in die Werkzeugkiste der Softwareentwicklung, nämlich zum Ruby-basierten Generator Jekyll. Jekyll selbst verwendet standardmäßig Markdown als Auszeichnungssprache, für AsciiDoc müssen wir ein klein wenig nachhelfen. Alternative Ansätze diskutieren wir im Textkasten „Alternativen zu Jekyll“.

In Folge 3 unserer Kolumne hatten wir die Generierung von PDFs aus AsciiDoc bereits kurz angerissen. In dieser Folge gehen wir auf ein paar Details ein, mit denen Sie die Klippen bei der Erstellung von PDFs gezielt umschiffen können (und davon gibts leider noch einige …).
 
 

„Jede hinreichend fortschrittliche Technologie ist von Magie nicht zu unterscheiden.“ Dieses Zitat von Arthur C. Clarke trifft auf vieles zu, was ein modernes Build-Skript stellenweise leistet. In dieser Folge unserer Kolumne lüften wir das Geheimnis und erklären einige der nützlichen Gradle-Features, die Sie für Ihre Dokumentation verwenden können. Sollte das Ihr erstes Date mit Gradle sein, empfehlen wir zuerst die Lektüre einer entsprechenden Einführung [1].

Im März fand zum siebten Mal die Greach, eine dem Groovy-und-Grails-Ökosystem gewidmete Konferenz, in Madrid/Spanien statt. In einer Keynote verkündete Graeme Rocher, Leiter des Grails-Framework-Teams, eine Überraschung: das Micronaut-Framework. Micronaut ist ein neues JVM-Framework, das von Grund auf für Microservices und Serverless-Computing-Umgebungen entwickelt wurde.

Eine Internetsuche nach den Stichworten „Asciidoc Tool“ liefert fürchterlich viele Treffer. Wir möchten den Dschungel der Möglichkeiten etwas lichten und Ihnen einige der weiter verbreiteten Werkzeuge kurz vorstellen. Dabei gehen wir vom konkreten Bedarf aus und möchten Tools vorstellen, die den Docs-as-Code-Ansatz konkret unterstützen.

Ein halbes Dutzend Folgen dieser Kolumne, bevor wir endlich zum Thema Sourcecode kommen: Wir möchten in Architekturdokumentation an manchen Stellen Code integrieren, etwa zur Beschreibung wichtiger Schnittstellen. AsciiDoc bietet hierfür schicke Features. Wie immer finden Sie den Quellcode dieser Kolumne online hier.

Wenn es um die Modellierung von Architekturen geht, also dem Erstellen eines Modells mit verschiedenen Sichten anstelle von unkorrelierten Zeichnungen, dann reicht das Einbinden von statischen Diagrammen oder PlantUML nicht mehr aus. Deshalb greifen wir in dieser Folge etwas tiefer in den Werkzeugkasten und integrieren echte Modelle in unseren Docs-as-Code-Ansatz.

Architekturdokumentation besteht hauptsächlich aus Fließtext, Tabellen und Diagrammen. Fließtext und Tabellen sollten nach der letzten Folge kein Problem mehr sein. Jetzt zeigen wir Ihnen mehrere Optionen, Diagramme in Ihre Dokumentation zu integrieren: Einerseits den einfachen Weg des Referenzierens (mit einigen möglichen Optionen) und alternativ Diagrams-as-Code, was gut zu Titel und Inhalt dieser Kolumne passt. So viel sei allerdings schon verraten: Leider eignet sich der letztgenannte (PlantUML-basierte) Ansatz nur für ganz wenige Arten von Diagrammen. Aber eins nach dem anderen – fangen wir mit den einfachen Dingen an.

In den letzten Ausgaben haben wir gezeigt, wie Sie AsciiDoc-Dokumente modular aufbauen und in verschiedene Zielformate wie PDF, DOCX oder Confluence konvertieren können. Diesmal gehen wir auf ein paar der Features von AsciiDoc ein, die unserer Meinung nach bei Architekturdokumentation nützlich sein können.

In der letzten Folge dieser Kolumne haben wir gezeigt, wie Sie Ihre AsciiDoc-Dokumente modular aufbauen können. In der dritten Folge der Kolumne erklären wir am Beispiel der Formate PDF, DOCX, Confluence und EPUB, wie sich verschiedene Ausgabeformate aus Ihrem AsciiDoc-Input erzeugen lassen.

In der letzten Ausgabe haben wir gezeigt, wie Sie mithilfe von AsciiDoc schnell zu ordentlich gestalteten Dokumenten kommen können. In der zweiten Folge unserer Kolumne möchten wir Ihnen Strukturierung und Modularisierung von Dokumentation vorstellen, einerseits zur Erleichterung von Teamarbeit, andererseits zur Verwendung einzelner Dokuteile für verschiedene Zielgruppen.

Dokumentation gehört zu den großen Übeln der Softwarezunft. Denn Software zu dokumentieren ist oft mühselig, zeitraubend und schlicht und ergreifend langweilig. Dass dem nicht so seien muss, zeigen die beiden Autoren Gernot Starke und Ralf D. Müller in ihrer neuen Kolumne. Ihr Ansatz ist die Dokumentation wie Code zu behandeln: Docs as Code.