Upcoming Talks

2022

15.03.: Talk: Rock Solid Software Architecture with ADRs, arc42 and Microsites

Past Talks

12.10.: Workshop: Modern software architecture documentation hands on

06.10.: Workshop: Moderne Softwarearchitekturdokumentation

05.10.: Talk: Moderne Softwarearchitekturdokumentation

JCon, online, 05.10., ralfdmueller sippsack

24.09.: Workshop: Moderne Softwarearchitekturdokumentation

Herbscampus, online, 24.09., ralfdmueller sippsack

15.09.: Talk: Portfolio as Code – Homepage für ITler

13.04.: Docs-as-Code

JUG CH, Online, 13.04., ralfdmueller

25.03.: Docs-as-Code

JUG Hessen, Online, 25.03., ralfdmueller

16.03.: Doku-Microsites mit jBake

JavaLand, Brühl/Online, 16.03., ralfdmueller

03.03.: Tutorial: Moderne Softwarearchitekturdokumentation

07.02.: Docs-as-Code with AsciiDoc & docToolchain

FOSDEM, Online, 07.02., ralfdmueller

2020

09.12.: Spock und AsciiDoc – Vom Test zur Spezifikation und zurück

IT-Tage, Online, 09.12., ralfdmueller

02.09.: Spock und AsciiDoc - vom Test zur Spezifikation und zurück

23.07.: Spock vs Supermutanten: Spezifikationstesten trifft Mutationstesten

20.02.: Spock und AsciiDoc - Vom Test zur Spezifikation und zurück

18.02.: Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

04.02.: Spock vs Supermutanten: Spezifikationstesten trifft Mutationstesten

2019

10.12.: Docs-as-Code: Anatomie einer smarten Systemdokumentation

IT-Tage, Frankfurt, 10.12., gernotstarke ralfdmueller

13.09.: Spock and AsciiDoc - ein perfektes Paar

JUG Saxony Day, Radebeul, 13.09., ralfdmueller

19.06.: Spock and AsciiDoc - a perfect match

Write the Docs, Karlsruhe, 19.06., ralfdmueller

07.06.: BDD mit Spock und Geb

05.06.: Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

08.05.: Docs as Code, arc42, AsciiDoc, Gradle und Antora im Einsatz

JAX 2019, Mainz, 08.05., ralfdmueller

08.04.: Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

JUG Dortmund, Dortmund, 08.04., ralfdmueller

19.03.: Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

JavaLand 2019, Brühl, 19.03., ralfdmueller

22.01.: Docs-as-Code: Anatomie einer smarten Systemdokumentation

OOP 2019, München, 22.01., gernotstarke ralfdmueller

2018

06.11.: Docs-as-Code: Anatomie einer realen Systemdokumentation

W-Jax 2018, München, 06.11., gernotstarke ralfdmueller

28.08.: Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

Java User Group Frankfurt, Deutsche Nationalbibliothek Frankfurt, 28.08., ralfdmueller

26.04.: Docs-as-Code - Architekturdokumentation leicht gemacht

JAX 2018, Mainz, 26.04., ralfdmueller sippsack

31.03.: Docs-as-Code: arc42, AsciiDoc, Gradle & Co. combined

Gr8conf-Conf, Copenhagen/Denmark, 31.03., ralfdmueller

21.02.: Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

21.02.: Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

2017

07.12.: Docs-as-Code

JUG Darmstadt, Darmstadt, 07.12., ralfdmueller sippsack

18.09.: Hitchhikers Guide to Architecture Documentation

27.06.: The Hitchhikers Guide to painless Documentation

DB, Frankfurt, 27.06., ralfdmueller

10.05.: Dokumentation am (Riesen-)Beispiel - arc42, AsciiDoc und Co. in Aktion

2016

Details

Dokumentation am (Riesen-)Beispiel – arc42, AsciiDoc und Co. in Aktion

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.

g

Ideen

Dieser Abschnitt enthält Ideen für Talks, die noch ausgearbeitet werden müssen.

Doku-Microsites mit jBake

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.

Documentation Driven Development

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.

5 Jahre Docs-as-Code mit docToolchain

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 :-)