Docs-as-Code - Architekturdokumentation leicht gemacht

Docs-as-Code - Architekturdokumentation leicht gemacht

Vortrag vom 26.04.2018 auf der JAX Mainz mit Falk Sippach

https://jax.de/software-architecture/the-hitchhikers-guide-to-docs-as-code/

https://doctoolchain.github.io
https://doctoolchain.github.io/docToolchain
https://jaxenter.de/tag/hhgdc
https://docs-as-co.de
https://arc42.org
https://rdmueller.github.io
https://twitter.com/RalfDMueller
https://twitter.com/docToolchain

Technische Dokumentation sollte man nicht mit Textverarbeitungsprogrammen erzeugen. Stattdessen ergibt es Sinn, die Erstellung in die normalen Entwicklungsprozesse einzubeziehen, sie zu automatisieren (Continuous Documentation) und mit den typischen Werkzeugen der Entwickler sowie mittels leichtgewichtigen Textformaten zu bearbeiten (Documentation as Code).

Anhand einer Architekturdokumentation zeigen wir, wie Sie mit dem arc42-Template im AsciiDoc-Format und Gradle als Build-Tool einfach Diagramme in Ihre Dokumentation integrieren, Stakeholder-spezifische Dokumente erzeugen und verschiedene Ausgabeformate generieren. Reviewfähige PDF-Dokumente? Publishing nach Confluence? Integration einer Präsentation? Alles kein Problem! Einige Teile der Doku können Sie sogar automatisiert testen. Zwischendurch bekommen Sie zahlreiche Tipps, wie und wo Sie systematisch den Aufwand für Dokumentation reduzieren können und trotzdem lesbare, verständliche und praxistaugliche Ergebnisse produzieren. Dokumentieren soll endlich auch Spaß machen.

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

April 26, 2018
Tweet