Hitchhikers Guide to Docu-as-Code
Source und Infos zur JavaMagazin-Kolumne 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.
Pro Folge der Kolumne haben wir Beispiele etc. in eigene Unterverzeichnisse organisiert.
Folge-1: Einführung
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: 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: 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: Diagramme, Teil 1
Diesmal geht es um Bilder und Diagramme, mit/ohne Bildunterschriften, laufende Nummerierung und (einfaches) Styling.
Folge-6: Diagramme, Teil 2
Die Fortsetzung - weiterführende Themen zu Diagrammen und Bildern.
Folge-7: Sourcecode
Sourcecode in Dokumentation, Syntax-Highlighting, Code direkt aus dem Repo inkludieren (jawohl - ohne copy/paste!).
Folge-8: Tools
Einige Werkzeuge, die wir (Ralf + Gernot) zum arbeiten mit AsciiDoc für Sie ausprobiert haben.