Moderne Softwarearchitekturdokumentation (DE) - Training / Workshop von Trivadis Holding AG

Man kann zwar an vielen Stellen nachlesen, wie man Architekturdokumentation strukturiert. Aber auf der Suche nach einer praktikablen Handhabung zur Erstellung und Pflege enden die meisten Versuche in der WYSIWYG-Hölle einer Textverarbeitung oder im tiefen Schlund eines Wikis. Dieses Seminar zeigt aufbauend auf bestehenden 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 von Softwarearchitektur, das Generieren von Inhalten aus dem Modell, Datenbankschema und 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 Dokumente ausliefern. Zudem lässt sich die Erstellung der Dokumentation in den Reviewprozess integrieren und so stetig verbessern und weiterentwickeln.

Einführung

• Vorgehensweisen und Sichten
• Probleme mit klassischen Dokumentationsansätzen
• Strukturierung von Architekturdokumentation (arc42)

Leichtgewichtige Markupsprachen

• Markdown
• AsciiDoc
• Integration von Templates (Corporate Design)
• Werkzeuge zur Erstellung und Voransicht

Documentation as Code

• Ablage im Code-Repo
• Integration in die tägliche Entwicklungsarbeit
• Versionierung und Historisierung

Continuous Documenation

• Automatisierung
• Build-Management
• Dokumentations-Workflow
• Dokumentations-Reviews

Einbetten und Generieren von Inhalten

• Beschreibung von APIs
• Einbetten von Sourcecode
• Generieren von Inhalten
• Erstellung von Präsentationen
• Validierung der generierten Inhalte

Einbetten von Grafiken

• Werkzeuge zur Erstellung von Grafiken
• Textbasierte Grafiken mit PlantUML, ditaa und Graphviz dot
• Einbetten in Markup-Sprachen
• Generieren von Diagrammen

Lebendige Dokumentation

• Effektive Erstellung
• Ausführbare Dokumentation
• Testen der APIs
• Testen und Dokumentieren von Architekturregeln

Fazit und Ausblick

• Rolle Dokumentationsverantwortlicher
• Nutzungsszenarien
• Integration mit Wikis/Blogs
• Best Practices

• Erfahre, wie man schlank und doch effizient dokumentiert
• Probiere aus, wie man Dokumentationen optimal in den Entwicklungsprozess integriert
• Wir zeigen, wie man Dokumentation aktuell hält und regelmäßig validiert