Anhand eines großen Systems zeigen Gernot und Ralf, wie Sie mit ziemlich wenig Aufwand angemessene und vernünftige Dokumentation für unterschiedliche Stakeholder produzieren – sodass Entwicklungsteams dabei auch noch Spaß haben.

Unser Rezept: AsciiDoc mit arc42 mischen, Automatisierung mit Gradle und Maven hinzufügen und mit Diagramm- oder Modellierungstools Ihrer Wahl kombinieren. Schon sind schicke HTML- und reviewfähige PDF-Dokumente fertig. Auf Wunsch gibts DOCX und Confluence als Zugabe.

Wir zeigen, wie Sie Doku genau wie Quellcode verwalten können, stakeholderspezifische Dokumente erzeugen und Diagramme automatisiert integrieren können. Einige Teile dieser 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.

Dokumentation in Markdown oder AsciiDoc zu erstellen ist einfach. GitHub, GitLab und Bitbucket zeigen die Dokumente schon gleich im Repository als HTML-Seite an.

Doch wie bekomme ich aus diesen Dokumenten jetzt eine schicke Website hin, die nicht nur das Projekt dokumentiert, sondern auch das Projekt über eine nette Landingpage vorstellt, die Architektur bereitstellt und einen Newsfeed anbietet?

In diesem Vortrag zeige ich, warum sich jBake gerade für Java-Projekte ausgezeichnet eignet, um für jedes Projekt mit wenig Aufwand eine schicke Microsite zu erstellen. Vom Plain-Text-Dokument bis zur veröffentlichten Website mit TLS.

Dabei werde ich viele Tricks und Kniffe aus dem Projektalltag einfließen lassen. Landingpage, Architekturdokumentation mit arc42, Anwender-Doku mit AsciiDoc, Blog mit RSS-Feed und eine Suche werden kombiniert und einfach in das bestehende Projekt-Repository entsprechend dem Docs-as-Code-Ansatz integriert. Über ein Open Source Template wird er Einstieg in die Erstellung einer eigenen Microsite nach dem Vortrag erleichtert.

Was passiert, wenn ein Entwickler sich intensiv mit dem Docs-as-Code Ansatz beschäftigt und ihn auf die Spitze treibt? Richtig - Dokumentation etnwickelt sich von der Nebensache, die man erledigt, wenn das Projekt läuft (also nie) zur zentralen Komponente, die zuerst erstellt wird und nach der das Projekt umsetzt wird.

Durch Docs-as-Code besteht die Dokumentation nicht mehr aus verschiedensten Fragmenten wie Anforderungen, Stories und Architektur, die alle in unterschiedlichen Systemen verwaltet werden und somit Medienbrüche unumgängig machen.

Die Anforderungen können nun in einem System mit Stories angereichert und diese durch Akzeptanzkriterien untermauert werden. Durch Transformationen wird aus den Akzeptanzkriterien ein Test-Gerüst, welches vom Entwickler durch Testimplementierungen belebt wird. An dieser Stelle geht der Ansatz dann von Documentation-Driven auf Test-Driven über.

Die Ergebnisse ausführbaren Akzeptanztests werden möglichst anscheilich wieder in die Stories und somit Anforderungen zurückgespielt und das Projekt erhält somit eine ausführbare Spezifikation.

In dieser Session nehme ich alle Teilnehmer mit auf einen kurzen Ausflug durch 5 Jahre docToolchain. Auf dieser Reise werden wir zwei Zeitstränge betrachten.

Zum Einen die Entwicklung des Docs-as-Code Ansatzes vom einfachen "Markdown im Repository" bis zu neueren Entwicklungen wie z.B. komfortablen Text-Editor-Plugins in der IDE oder Documentation-Driven-Development.

Zum Anderen werde ich über meine Reise mit dem Open-Source-Projekt docToolchain, vom Script zum Tool berichten. Erfahrungsbericht pur :-)