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

Eine Folge von Artikeln für Informatik-Aktuell von R.D. Müller und G. Starke

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:

Einführung

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

https://docs-as-co.de