Ralf Müller und Falk Sippachs Session von der JAX 2018

Docs as Code – Architekturdokumentation leicht gemacht

Redaktion JAXenter

Dokumentation ist unter Softwareentwicklern nicht sonderlich beliebt – es ist mühsam und kostet Zeit. Doch das muss nicht sein! Auf der JAX 2018 zeigten Ralf Müller und Falk Sippach in ihrer Session eine Alternative: Docs as a Code

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 Ralf Müller und Falk Sippach in ihrer Session auf der JAX 2018, wie man mit dem arc42-Template im AsciiDoc-Format und dem Gradle als Build-Tool einfach Diagramme in die Dokumentation integrieren, Stakeholder-spezifische Dokumente erzeugen und verschiedene Ausgabeformate generieren kann. Reviewfähige PDF-Dokumente? Publishing nach Confluence? Integration einer Präsentation? Alles kein Problem! Einige Teile der Doku können man sogar automatisiert testen. Zwischendurch gibt es zahlreiche Tipps, wie und wo man systematisch den Aufwand für Dokumentation reduzieren kann und trotzdem lesbare, verständliche und praxistaugliche Ergebnisse produziert. Dokumentieren soll endlich auch Spaß machen.

Docs as Code – Architekturdokumentation leicht gemacht von JAX TV auf Vimeo.

Ralf D. Müller ist ambitionierter Grails-Entwickler und versucht stetig, seine Arbeit weiter zu vereinfachen. Zurzeit beschäftigt er sich insbesondere mit der Verbesserung der ganzheitlichen Dokumentation von Projekten – vor allem mithilfe des arc42-Templates.
Falk Sippach hat über fünfzehn Jahre Erfahrung im Java- und JavaScript-Umfeld und ist als Trainer, Softwareentwickler und Projektleiter bei der OIO Orientation in Objects GmbH tätig. Wenn er dazu kommt, schreibt er Blogeinträge und Artikel und tritt gelegentlich bei Konferenzen auf. In seiner Wahlheimat Darmstadt organisiert er mit anderen die örtliche Java User Group.

Verwandte Themen:

Geschrieben von
Kommentare

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu: