Moderne Softwarearchitekturdokumentation

Architecture documentation is very often treated stepmotherly. Yet documentation supports the design work and creates transparency and guard rails for the implementation and maintenance of the software architecture. On the one hand, it is not simple however to hold the important information from the draft of the software architecture structured and easily understandable. On the other hand, most attempts in search of practicable handling for creation and maintenance end in the WYSIWYG hell of a word processor or the deep maw of a wiki. Building on lightweight tools and text formats, this workshop shows how to create documentation that is as redundancy-free as possible and can be delivered in appealing formats optimized for different target groups. With the help of many practical exercises, the seminar deals with concepts such as Continuous Documentation and Documentation as Code. The goal is modern, effective, and pragmatic documentation of software architecture. We build on proven methods, formats, and tools like AsciiDoc/Markdown, PlantUML, docToolchain, Maven/Gradle, jqAssistant, and many more. In detail, we take care of the automation of the documentation build process, the generation of content from the model, database schema or source code, the structured storage including versioning and historicization, and the use or creation of meaningful and easily maintainable graphics. Agile development teams can thus integrate documentation work into their daily tasks and deliver up-to-date, comprehensive, and well-structured results at any time. In addition, the creation of documentation can be integrated into the review process and thus constantly improved and further developed.

Architekturdokumentation wird sehr oft stiefmütterlich behandelt. Dabei unterstützt das Dokumentieren bei der Entwurfsarbeit, schafft Transparenz bzw. Leitplanken für die Umsetzung und Wartung der Softwarearchitektur. Einerseits ist es aber nicht einfach, die wichtigen Informationen aus dem Entwurf der Softwarearchitektur strukturiert und leicht verständlich festzuhalten. Andererseits enden die meisten Versuche auf der Suche nach einer praktikablen Handhabung zur Erstellung und Pflege in der WYSIWYG-Hölle einer Textverarbeitung oder im tiefen Schlund eines Wikis. Dieses Seminar zeigt aufbauend auf leichtgewichtigen Tools und Textformaten die Erstellung einer möglichst redundanzfreien Dokumentation, die für verschiedene Zielgruppen optimiert in ansprechenden Formaten ausgeliefert werden kann.

Anhand von vielen praktischen Ü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, jqAssistant und viele weitere. Im Detail kümmern wir uns um die Automatisierung des Dokumenations-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.

siehe auch Architekturdokumentation mit Microsites