Best Practices für (Architektur)dokumentation 

Ich spreche mit Falk Sippach über die Bedeutung und Methoden einer effizienten Architekturdokumentation. Wir gehen darauf ein, wie Dokumentation oft vernachlässigt wird und welche Lösungen es gibt, um dies zu vermeiden. Falk erläutert die Ansätze ‘Documentation as Code’ und ‘Continuous Documentation’, die es ermöglichen, Dokumentation wie Quellcode zu behandeln und kontinuierlich zu aktualisieren. Wir sprechen über die Nutzung von Tools wie Markdown und ASCII-Doc, um die Erstellung und Pflege von Dokumentationen zu vereinfachen. Mit vielen praktischen Beispielen und Tipps zeigt Falk, wie Entwickler und Tester ihre Dokumentation leichtgewichtig und effektiv gestalten können.

Gepräch mit Falk Sippach zu Architekturdokumentation

“Documentation as Code ist die Idee, dass wir die Dokumentation wie Source Code behandeln, also die selben Werkzeuge nutzen können und das Ganze auch in Build-Prozesse integrieren, automatisieren können.” – Falk Sippach

Falk Sippach ist als Softwarearchitekt, Berater und Trainer stets auf der Suche nach dem Funken Leidenschaft, den er bei seinen Teilnehmern, Kunden und Kollegen entfachen kann. Bereits seit 20 Jahren unterstützt er in meist agilen Softwareentwicklungsprojekten im Java-Umfeld. Als aktiver Bestandteil der Community (Mitorganisator der JUG Darmstadt und Mitglied der Java Champions) teilt er zudem sein Wissen gern in Artikeln, Blog-Beiträgen, sowie bei Vorträgen auf Konferenzen oder User Group Treffen und unterstützt bei der Organisation diverser Fachveranstaltungen.

Highlights aus der Episode:

• Dokumentation ist für Tester wichtig als Testbasis und Nachschlagewerk.
• Falk erklärt, wie Dokumentation oft vernachlässigt wird und warum das so ist.
• Documentation as Code bedeutet, Dokumentation wie Source Code zu behandeln und in Textformaten wie Markdown oder ASCII-Doc zu schreiben.
• Continuous Documentation integriert die Dokumentation in den gesamten Entwicklungsprozess, ähnlich wie Continuous Integration und Continuous Delivery.
• Integration von Bildern und Diagrammen in die Dokumentation

Effiziente Architekturdokumentation

In dieser Podcast-Episode spreche ich mit Falk Sippach über die Bedeutung und Herausforderung der Architekturdokumentation. Falk stellt leichtgewichtige Ansätze wie ‘Documentation as Code’ und ‘Continuous Documentation’ vor, die Entwicklern helfen, Dokumentation effizienter zu verwalten.

Einführung in die Welt der Architekturdokumentation

Hallo und herzlich willkommen zur neuen Folge unseres Software-Testing-Podcasts! Ich bin Richie, euer Host, und sende live von der OOP 2024 aus München. Dieses Mal habe ich Falk Sippach zu Gast. Wir haben uns intensiv über Architekturdokumentation unterhalten – ein Thema, das auch für uns Tester von großer Bedeutung ist. Dokumentation dient als Testbasis und Nachschlagewerk, weshalb sie unverzichtbar ist. In unserem Gespräch hat Falk wertvolle Ansätze vorgestellt, wie man Dokumentation leichtgewichtig gestalten kann.

Warum Dokumentation oft vernachlässigt wird

Falk hat ein Problem angesprochen, das viele Entwickler kennen: Dokumentation wird oft als nachrangig betrachtet. Prioritäten liegen häufig auf der Fertigstellung von Projekten und weniger auf der Dokumentation. Viele Entwickler empfinden das Schreiben von Dokumentationen als lästig im Vergleich zum eigentlichen Programmieren. Zudem sind die dafür benötigten Tools oft nicht optimal integriert. Eine Umfrage während seines Vortrags bestätigte die vielfältigen Gründe: hoher Aufwand, komplizierte Tools und die Annahme, dass ohnehin niemand die Dokumentation liest.

Leichtgewichtige Ansätze: Documentation as Code und Continuous Documentation

Falk stellte zwei zentrale Konzepte vor: ‘Documentation as Code’ und ‘Continuous Documentation’. Beim ‘Documentation as Code’ wird die Dokumentation ähnlich wie Source Code behandelt. Das bedeutet, dass man einfache Textformate wie Markdown oder AsciiDoc nutzt und diese in bestehende Build-Prozesse integriert. Der zweite Ansatz, ‘Continuous Documentation’, strebt danach, die Dokumentationsarbeit iterativ und inkrementell in den Entwicklungsprozess einzubinden. Somit bleibt die Doku immer aktuell und wird kontinuierlich verbessert.

Praktische Umsetzung von Documentation as Code

Die Umsetzung von ‘Documentation as Code’ ist laut Falk überraschend einfach. Man benötigt keine zusätzlichen Tools; Texteditoren oder IDEs reichen aus. Man schreibt die Dokumentation in Textdateien neben dem Source Code und kann diese dann automatisiert zu PDFs oder HTML-Seiten verarbeiten lassen. Besonders wertvoll ist hierbei die Modularisierung der Dokumente, wodurch sie übersichtlich bleiben und leichter gepflegt werden können.

Diagramme effizient integrieren

Ein Bild sagt mehr als tausend Worte – das gilt besonders für technische Dokumentationen. Falk erläuterte verschiedene Methoden zur Integration von Diagrammen: Von einfachen Binärformaten wie PNG oder JPEG bis hin zu Vektorgrafiken mit DrawIO oder PlantUML. Letzteres erlaubt es sogar, Diagramme als Text zu schreiben und direkt in den Quellcode zu integrieren. Dadurch bleibt alles versionierbar und nachvollziehbar.

Continuous Documentation als Teil des Entwicklungsprozesses

Ein zentraler Punkt unseres Gesprächs war, wie man ‘Continuous Documentation’ in den Entwicklungsprozess integrieren kann. Indem man die Generierung der Dokumentation in bestehende Build-Prozesse einbindet, bleibt diese immer aktuell. CI/CD-Pipelines können so konfiguriert werden, dass jede Änderung im Source Code automatisch auch die entsprechende Doku aktualisiert. Dies sorgt nicht nur für Konsistenz sondern erhöht auch die Akzeptanz unter den Entwicklern.