Zurück

Moderne Softwarearchitekturdokumentation

24. September 2021, 9–16 Uhr

Architekturdokumentation wird oft stiefmütterlich behandelt. Dabei unterstützt sie bei der Entwurfsarbeit, schafft Transparenz bzw. Leitplanken für die Umsetzung und Wartung der Architektur. Einerseits ist es nicht einfach, die wichtigen Informationen aus dem Entwurf strukturiert und leicht verständlich festzuhalten. Andererseits enden die meisten Versuche auf der Suche nach einer praktikablen Handhabung in der WYSIWYG-Hölle einer Textverarbeitung oder im tiefen Schlund eines Wikis.

Dieses Tutorial zeigt aufbauend auf leichtgewichtigen Tools und Textformaten die Erstellung einer möglichst redundanzfreien Dokumentation, die für verschiedene Zielgruppen optimiert ausgeliefert werden kann.

Anhand vieler praktischer Übungen geht es um Begriffe wie Continuous Documentation und Documentation as Code. Das Ziel ist die moderne, effektive und pragmatische Dokumentation der Softwarearchitektur. Wir bauen auf bewährte Methoden, Formate und Tools wie AsciiDoc/Markdown, PlantUML, docToolchain, Maven/Gradle und viele weitere. Im Detail kümmern wir uns um die Automatisierung des Dokumentations-Build-Prozesses, das Generieren von Inhalten aus dem Modell, Datenbankschema oder Sourcecode, die strukturierte Ablage inklusive Versionier- und Historisierbarkeit und die Verwendung bzw. Erstellung von aussagekräftigen und einfach wartbaren Grafiken.

Agile Entwicklungsteams können so die Dokumentationsarbeit in ihre täglichen Aufgaben integrieren und jederzeit aktuelle, umfassende und gut strukturierte Ergebnisse ausliefern. Zudem lässt sich die Erstellung der Dokumentation in den Reviewprozess integrieren und so stetig verbessern und weiterentwickeln

Vorkenntnisse

  • Interesse an Softwarearchitekturdokumentation
  • Bereit für alternative Wege bei der Dokumentation zu sein

Lernziele

  • Leichtgewichtige Dokumentation anwenden
  • Dokumentationsinhalte kennenlernen
  • Erzeugung der Dokumentation automatisiert in den Entwicklungsprozess einbinden
  • Strukturierung nach arc42 umsetzen
  • Leichtgewichtige Tools/Formate wie AsciiDoc und PlantUML einsetzen
  • Microsites als Einstieg für den Architekturüberblick einsetzen

Agenda

Folgende Agenda haben wir geplant. Wir werden die Themen jedoch flexibel, je nach Bedarf umsetzen.

  • Einführung
  • Documentation as Code
  • docToolchain
  • Architektur dokumentieren
  • Praktische Umsetzung
  • Weiterführende Themen
  • Fazit und Ausblick

    •  

    Technische Anforderungen

    Wir werden in dem Workshop sowohl Theorie vermitteln aber auch viele Beispiele bringen, die Ihr gleich nachvollziehen könnt. Damit das gut klappt, solltet Ihr einen Rechner mit folgenden Voraussetzungen zur Hand haben:
    • Deine Netzwerkverbindung sollte möglichst “offen” sein, also ohne einschränkende Proxies
    • Unter Windows wäre WSL2 hilfreich. Powershell geht auch
    • eine IntelliJ basierte IDE erleichtert das Editieren
      • Community Edition reicht aus
      • um Zeit zu sparen könntest Du schon das AsciiDoc und das diagrams.net Plugin installieren
    • andere Editoren funktionieren als Basis auch
    • Java in einer Version zwischen 8 und 14 (8<= Java Version <= 14)
    • Falls kein entsprechend offener Rechner zur Verfügung steht, kannst Du auch mit einem kostenlosen Account auf http://gitpod.io/ die Beispiele nachvollziehen

    Speaker

     

    Falk Sippach
    Falk Sippach arbeitet bei der embarc Software Consulting GmbH als Softwarearchitekt, Berater und Trainer. Bereits seit über 15 Jahren unterstützt er in meist agilen Softwareentwicklungsprojekten im Java-Umfeld. Als aktiver Bestandteil der Community (JUG Darmstadt) teilt er zudem sein Wissen gern in Artikeln sowie bei Vorträgen und unterstützt bei der Organisation diverser Fachveranstaltungen.

    Ralf D. Müller
    Ralf D. Müller ist ambitionierter Groovy- & Grails-Entwickler und versucht stetig, seine Arbeit weiter zu vereinfachen. Zurzeit beschäftigt er sich insbesondere mit der Verbesserung der ganzheitlichen Dokumentation von Systemen, vor allem mit Hilfe des arc42-Templates und AsciiDoc. Er arbeitet als Software Engineering Advocate bei der DB Systel, der IT-Tochter und dem Digitalpartner der Deutschen Bahn.

     

    Jetzt Tickets sichern

    Herbstcampus-Newsletter

    Ihr möchtet über den Herbstcampus
    auf dem Laufenden gehalten werden?

     

    Anmelden