Best Practices für (Architektur)dokumentation

Architekturdokumentation fällt oft hinten runter, weil sie aufwändig, mühsam und schnell veraltet ist. Der Ansatz Documentation as Code dreht das um: Dokumentation wird in leichtgewichtigen Textformaten direkt im Code-Repository gepflegt, automatisch gebaut und über die CI/CD-Pipeline ausgeliefert. Sogar Diagramme lassen sich als Text schreiben, versionieren und in Review-Prozesse einbinden – eine Erleichterung für Entwickler und ein Gewinn für alle, die auf aktuelle Dokumentation als Grundlage für Software Testing angewiesen sind.

Podcast Episode: Best Practices für (Architektur)dokumentation

In dieser Folge sprechen wir über die Bedeutung und Methoden einer effizienten Architekturdokumentation. Dabei thematisieren wir, wie Dokumentation oft vernachlässigt wird und welche Lösungen es gibt, um dies zu vermeiden. Die Ansätze ‘Documentation as Code’ und ‘Continuous Documentation’ ermöglichen es, Dokumentation wie Quellcode zu behandeln und kontinuierlich zu aktualisieren. Zudem befassen wir uns mit der Nutzung von Tools wie Markdown und ASCII-Doc, die den Prozess der Erstellung und Pflege von Dokumentationen erleichtern. Anhand zahlreicher praktischer Beispiele und Tipps wird verdeutlicht, wie Entwickler und Tester ihre Dokumentation leichtgewichtig und effektiv gestalten können.

„Word ist nicht dafür gemacht, dass man große Sachen schreibt.” - 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 der Episode

• Architekturdokumentation scheitert meist an falschen Tools, fehlender Priorisierung und mangelndem Spaß beim Schreiben.
• Documentation as Code: Doku in Markdown/AsciiDoc schreiben, in Git versionieren, automatisch bauen.
• DrawIO speichert Vektordaten in PNG-Metadaten – editierbar bleiben, ohne separaten Export-Schritt.
• Diagrams as Code mit PlantUML macht Diagramme versionierbar, vergleichbar und reviewbar wie Sourcecode.
• Definition of Done muss Doku-Updates enthalten – sonst fällt sie im Code-Review durch.

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.