HHGDC

Hitchhiker’s Guide to Docs as Code: Websites mit AsciiDoctor & Jekyll

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“.

Hitchhiker’s Guide to Docs as Code: Build-Magie

„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].

Hitchhiker’s Guide to Docs-As-Code: Diagramme, aber richtig…

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.

Modulare Dokumentationen: Wie man sie baut und warum sie die Teamarbeit erleichtern

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.