<commit_before>= image:./hhgdac-logo.png[] HHGDAC

**Hitchhikers Guide to Docu-as-Code**

Source und Infos zur JavaMagazin-Kolumne von https://rdmueller.github.io/[R.D. Müller] und http://gernotstarke.de[G. Starke]

== Schmerzfreie Dokumentation
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.


== How-To's

=== Voraussetzungen

* https://gradle.org/install[Gradle] installiert zu haben, hilft ungemein... Wir bevorzugen die Installation über http://sdkman.io/[sdkman], den großartigen Package-Manager.
* Eine Shell/Kommandozeile/Terminal.

=== Folge-1: Einführung
Wir haben einen Wrapper für Gradle zugefügt - das macht den Einstieg für Sie noch einfacher:

    cd folge-1
    ./gradlew asciidoctor


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

    cd folge-1
    gradle asciidoctor

Das Ergebnis, die Datei `hello.html`, wird ins Verzeichnis
`./build/asciidoc/html5` generiert.<commit_msg>korrigiere readme-folge-2.adoc<commit_after>= image:../hhgdac-logo.png[] Folge-2: Modularisierung

[small]
--
Source und Infos zur JavaMagazin-Kolumne von
https://rdmueller.github.io/[R.D. Müller] und
http://gernotstarke.de[G. Starke]
--


Diesmal geht es um die Aufteilung von Dokumentation in einzelne Teile -
damit auch (größere) Teams die Arbeit an Doku ordentlich aufteilen können.

AsciiDoc stellt dafür einen leistungsfähigen Befehl bereit:

`include::path[]`

Wir fangen mit einem kleinen Beispiel an -
ein Masterdokument inkludiert zwei andere Dateien,
die ein einem Unterverzeichnis `kapitel` liegen.

Aber sehen Sie selbst:

    cd folge-2
    ./gradlew asciidoctor


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

    cd folge-2
    gradle asciidoctor
{'fraction_non_alphanumeric': 0.0897629853756934, 'fraction_numerical': 0.004034291477559254, 'mean_word_length': 4.391304347826087, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 3, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7630095', 'n_tokens_mistral': 738, 'n_tokens_neox': 722, 'n_words': 206}