HHGDAC

HHGDAC copied to clipboard

= image:./hhgdac-logo.png[] HHGDAC :toc: right

Hitchhikers Guide to Docu-as-Code

[small]

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.

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

== Die Folgen...

Pro Folge der Kolumne haben wir Beispiele etc. in eigene Unterverzeichnisse organisiert.

=== Folge-1: https://github.com/arc42/HHGDAC/tree/master/folge-1[Einführung]

=== Folge-2: https://github.com/arc42/HHGDAC/tree/master/folge-2[Modulare Dokumentation]

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

Wir zeigen, wie Sie Dokumentation auf verschiedene Teile ("Module") aufteilen können, und diese in AsciiDoc durch 'include' Statements wieder zusammenfügen.

=== Folge-3: https://github.com/arc42/HHGDAC/tree/master/folge-3[Verschiedene Ausgabeformate]

Wir zeigen, wie Sie (neben html) auch pdf, docx, confluence, epub und Co. als Ausgabeformate generieren können - alles aus ein- und derselben AsciiDoc-Basis.

=== Folge-4: https://github.com/arc42/HHGDAC/tree/master/folge-4[AsciiDoc Cheatsheet]

Wir zeigen diejenigen AsciiDoc-Features, die unserer Meinung nach für praktische Architekturdokumentation (etwa nach arc42) nützlich sind.

Wir stellen diese Features in einer Art Cheat-Sheet dar, bei dem Sie die jeweiligen Features immer direkt mit den daraus erzeugten Ergebnissen sehen können.

=== Folge-5: https://github.com/arc42/HHGDAC/tree/master/folge-5[Diagramme, Teil 1] Diesmal geht es um Bilder und Diagramme, mit/ohne Bildunterschriften, laufende Nummerierung und (einfaches) Styling.

=== Folge-6: https://github.com/arc42/HHGDAC/tree/master/folge-6[Diagramme, Teil 2] Die Fortsetzung - weiterführende Themen zu Diagrammen und Bildern.

=== Folge-7: https://github.com/arc42/HHGDAC/tree/master/folge-7[Sourcecode] Sourcecode in Dokumentation, Syntax-Highlighting, Code direkt aus dem Repo inkludieren (jawohl - ohne copy/paste!).

=== Folge-8: https://github.com/arc42/HHGDAC/tree/master/folge-8[Tools] Einige Werkzeuge, die wir (Ralf + Gernot) zum arbeiten mit AsciiDoc für Sie ausprobiert haben.

=== Folge-9: Build-Magie Wir erklären ein paar nützliche Gradle-Features.

=== Folge-10: https://github.com/arc42/HHGDAC/tree/master/folge-10[PDF]

=== Folge-11: https://github.com/arc42/HHGDAC/tree/master/folge-11-jekyll[Websites mit AsciiDoctor, Jekyll und Docker]

== Links und weitere Infos

(oops - hier müssen wir noch Links nachpflegen...)

• AsciiDoctor Home
• AsciiDoctor Writers Guide
• AsciiDoc (der ursprüngliche, in Python geschriebene Prozessor)