Hitchhikers Guide to Docs-as-Code - Code + Infos zur JavaMagazin-Kolumne von R.D. Müller und G.Starke
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs
folge-09
folge-1
folge-10
folge-11-jekyll
folge-2
folge-3
folge-4
folge-5
folge-6
folge-7
folge-8
jekyll-docker-adoc
.gitignore
LICENSE
README.adoc
hhgdac-logo.png
icon.png

README.adoc

hhgdac logo HHGDAC

Hitchhikers Guide to Docu-as-Code

Source und Infos zur JavaMagazin-Kolumne von R.D. Müller und 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

  • Gradle installiert zu haben, hilft ungemein…​ Wir bevorzugen die Installation über 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: 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.

Folge-9: Build-Magie

Wir erklären ein paar nützliche Gradle-Features.

Folge-10: PDF

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

  • AsciiDoctor Home

  • AsciiDoctor Writers Guide

  • AsciiDoc (der ursprüngliche, in Python geschriebene Prozessor)