Software Testing & Qualität - Testautomatisierung, KI & Agilität

Best Practices für (Architektur)dokumentation - Falk Sippach

Listen Later
Dokumentation als Code

📌 Konferenz-Tipp: TACON 2026 in Leipzig (16.–17. September). Ich war letztes Jahr als Keynote dort und fand den Austausch richtig gut 👉 https://swt.fm/tacon

„Word ist nicht dafür gemacht, dass man große Sachen schreibt." - Falk Sippach

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.

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:

  • Documentation as Code behandelt Architekturdokumentation wie Quellcode: gleiche Werkzeuge, Textformate wie Markdown oder AsciiDoc, versioniert in Git mit Diff-Fähigkeit und Review per Pull-Request.
  • AsciiDoc ist für technische Dokumentation die bessere Wahl als Markdown, weil es einen echten Standard bietet, Dokumente modularisieren kann und eine Single Source of Truth ermöglicht.
  • Diagramme als Text, etwa mit PlantUML, lassen sich versionieren und direkt vergleichen, scheitern aber bei größeren Architekturdiagrammen, weil das automatische Layout dann nicht mehr kontrollierbar ist.
  • Continuous Documentation bindet das Schreiben und Pflegen von Dokumentation in die CI/CD-Pipeline ein, sodass bei jedem Build die Doku mitgebaut und als PDF oder HTML ausgeliefert wird.
  • Fehlende Dokumentation fällt im Review-Prozess auf, wenn sie Teil der Definition of Done ist und unvollständige Dokumentation das Mergen eines Pull-Requests blockiert.

    • Danke an die Community-Partner des Podcasts:Alliance for Qualification | ASQF | Austrian Testing Board | dpunkt.verlag | German Testing Board | German Testing Day | GI Fachgruppe TAV | Heise | HANSER Verlag | ISTQB | iSQI GmbH | oop | QS-TAG | SIGS-DATACOM | skillsclub | Swiss Testing Board | TACON Credits: Sound | Grafik

    ...more
    View all episodesView all episodes
    Download on the App Store
    Software Testing & Qualität - Testautomatisierung, KI & AgilitätBy Richard Seidl - Experte für Software-Entwicklung und Testautomatisierung