Kontinuierliche Architekturdokumentation im agilen Umfeld Orientation in Objects GmbH Weinheimer Str. 68 68309 Mannheim www.oio.de Version: 1.0 [email protected] Doku-Smells Die 7 Sünden der Architekturdokumentation Foto von jesperbkskov: https://pixabay.com/en/fish-newspaper-food-russian-salted-224097/ (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 2 1 Ihr Sprecher Falk Sippach (@sippsack) Trainer, Berater, Entwickler Co-Organisator Architektur Agile Softwareentwicklung Codequalität Co-Organisator Commiter DukeCon © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 3 Java, XML und Open Source seit 1998 ) Software Factory ) ) Object Rangers ) ) Competence Center) • Schlüsselfertige Realisierung • Unterstützung laufender • Schulungen, Coaching, von Java Software Java Projekte Weiterbildungsberatung, Train & Solve-Programme • Individualsoftware • Perfect Match • Methoden, Standards und • Pilot- und Migrationsprojekte • Rent-a-team Tools für die Entwicklung • Sanierung von Software • Coaching on the project von offenen, unternehmens- • Software Wartung • Inhouse Outsourcing weiten Systemen © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 4 2 Abstract Textverarbeitungsprogramme sind für technische Dokumentation schlecht geeignet, ein Wiki auch nur bedingt. Wir betrachten zunächst einige sündhafte Doku-Smells und diskutieren anhand einiger Fallbeispiele, wie man Softwarearchitektur effizient und redundanzfrei erstellen und pflegen kann, wie man sie prüft und validiert, in Teilen generiert oder sogar als Regelsammlung ausführt. Automatisierung im Build-Prozess, schlanke Dokumentenformate, strukturierte Datenablage inklusive Versionierung, Historisierung, Vergleichbarkeit und die Bearbeitung im Team sind dabei wichtige Komponenten für die Konzepte Continuous Documentation und Documentation as Code. © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 5 Anforderungen klären Architektur Architektur bewerten entwerfen Architektur kommunizieren aus: Effektive Warum Warum dokumentieren? Softwarearchitekturen (G. Starke + P. Hruschka) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 6 3 Gründe für eine Architektur-Dokumentation Entwurfsunterstützung Kommunikation Bewertbarkeit Frage nach Warum Neue Mitarbeiter Grafik von The Practical Dev: https://github.com/thepracticaldev/orly-full-res/blob/master/notwritingdocs-big.png (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 7 Dokumentieren nervt • Falsche Werkzeuge • Dateiablage im Share-Laufwerk • Redundanzen • Textwüste • Handarbeit • Veraltet • Liest sowieso keiner! © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 8 4 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells - HANDARBEIT TOTE DOKU Doku ELFENBEINTURM © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 9 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells - HANDARBEIT TOTE DOKU Doku ELFENBEINTURM © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 10 5 Hauptsache, du machst es nicht mit Word! http://www.machsmit.de/kampagne/motive_der_kampagne/index.php © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 11 Textverarbeitung Visio Powerpoint UML-Tools Foto von Antranias: https://pixabay.com/en/telescope-view-distant-binoculars-1201497/ (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 12 6 Alternative Datenformate zu Textverarbeitung Plain-Text, leicht lesbar, einfach editierbar, automatisiert verarbeitbar Plain-Text kollaborativ eingeschränkte Lesbarkeit Wikis LaTex/DocBook visuell, kurz & knapp Austauschformat Mindmaps Richtext © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 13 Markdown Normaler Text wird so dargestellt wie eingegeben. *Kursiv*, **Fett** und ***Fett kursiv*** bzw. _Kursiv_, __Fett__ und ___Fett kursiv___ Markiert Text als `Inline-Quelltext` Ein Code-Block durch Einrückung mit vier Leerzeichen * Ein Punkt in einer ungeordneten Liste * Ein Unterpunkt, um vier Leerzeichen eingerückt 1. Ein Punkt in einer geordneten Liste 2. Ein weiterer Punkt 1. Noch ein Punkt bei mehrfacher Angabe derselben Ziffer # Überschrift in Ebene 1 #### Überschrift in Ebene 4 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 14 7 AsciiDoc © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 15 Welcher Markup-Typ bin ich? © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 16 8 Einheitliche Dokumentenstruktur (z. B. arc42) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 17 arc42 Templates © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 18 9 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells - HANDARBEIT TOTE DOKU Doku ELFENBEINTURM © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 19 Foto von UliSchu: https://pixabay.com/en/organization-register-folder-files-1205171/ (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 20 10 Unser täglich Entwickler-Brot: • Plain-Text • Entwicklungs- umgebung • Kommandozeilen- werkzeuge • Versions- verwaltung Foto von geralt: https://pixabay.com/de/unternehmer-start-start-up-karriere-696976/ (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 21 Code-Nähe Ablage im Repo Versionier-/diffbar Synchrone Auslieferung Offlinefähig Teil des Build-Prozess Generierung Automatisierung Flexible Ausgabeformate Documentation as Code Foto von ahobbit: https://pixabay.com/en/vault-business-bank-vault-bank-1144249/ (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 22 11 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells - HANDARBEIT TOTE DOKU Doku ELFENBEINTURM © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 23 Single Source of Truth Includes Quellcode verlinken Platzhalter einbetten Foto von pcdazero: https://pixabay.com/en/umbrellas-sea-holiday-summer-beach-921501/ (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 24 12 Inhalte generieren WSDL, Swagger DB-Schema Annotationen JavaDoc Markup generieren Foto von ClassicallyPrinted: https://pixabay.com/en/wind-turbine-energy-electricity-937715/ (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 25 Schnittstellenbeschreibung generieren © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 26 13 @startuml Quellcode PlantUML + interface DemoService DemoService <|-- DB-Schema AsciiDoc enum State { UML-Modell generieren NEW OPEN Konfiguration APPROVED# Werte von State IN_PROGRESS FIXED* NEW } * OPEN interface DemoService { * APPROVED String foobar(); @enduml* IN_PROGRESS } * FIXED class DemoServiceImpl implements DemoService { @Override public String foobar() { return "demo"; } } enum State { NEW, OPEN, APPROVED, IN_PROGRESS, FIXED } © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 27 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells - HANDARBEIT TOTE DOKU Doku ELFENBEINTURM © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 28 14 Ein Bild sagt mehr als tausend Worte! © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 29 Quelle für Bilder/Grafiken • Export aus UML-Modellen • Manuelle Erstellung (Bildverarbeitung/Visualisierungsprogramme) • Einbetten/Verlinken in Markup:  image::bild.png[Alternativtext] © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 30 15 B(u)ild-Tool? Paint? Sicher nicht! © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 31 Tools yEd ist ein kostenloses Visualisierungsprogramm … und Visio, Enterprise Architect, Magic Draw, … © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 32 16 Diagramme als textuelle Beschreibung © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 33 "AsciiArt" © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 34 17 Online- Tools © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 35 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells - HANDARBEIT TOTE DOKU Doku ELFENBEINTURM © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 36 18 Agile Projekte iterativ kontinuierlich Foto von Unsplash: https://pixabay.com/de/fluss-bachlauf-bach-l%C3%A4ndlich-768654/ (CC0 Public Domain Lizenz) © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 37 Agile Teams brauchen nicht dokumentieren! Endlich ... Häh? © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 38 19 Wer ist schuld? Laufende Software wichtiger als ausführliche Dokumentation http://agilemanifesto.org/background.jpg © Orientation