Docs-as-Code: (technische) Dokumentation in gut

Wir möchten Dokumentation in der Softwareentwicklung von vielerlei typischen Schmerzen befreien:

Wir generieren Dokumente, beispielsweise Architektur-, Schnittstellen- oder Betriebsdokumentation.
Wir arbeiten dabei DRY, modular und flexibel.
Wir erzeugen zielgruppenspezifische Ergebnisse, u.a. in HTML, pdf, docx oder Confluence.

Voraussetzungen

Gradle installiert zu haben, hilft ungemein… Wir bevorzugen die Installation über sdkman, den großartigen Package-Manager.
Eine Shell/Kommandozeile/Terminal.

Alternativ können Sie das Repository auch in gitpod.io öffnen, dann startet eine web-basierte Entwicklungsumgebung:

Wir haben einen Wrapper für Gradle zugefügt - das macht den Einstieg für Sie noch einfacher:

./gradlew asciidoctor

Falls Sie Gradle bereits installiert haben, geht’s auch so:

gradle asciidoctor

Das Ergebnis, die Datei hello.html, wird ins Verzeichnis ./build/asciidoc/html5 generiert, und sollte etwa wie folgt aussehen:

Viel Spass beim Experimentieren!

Gernot & Ralf