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:
![Alternativtext](bild.png "Bildtitel hier") 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 in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 39
Worauf das agile Manifest eigentlich abzielte …
Documentation through the Software Development Lifecycle
http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 40
20 Automatisiert erstellen Regelmässig ergänzen Reviewen Nachbessern
Continuous Documentation
Foto von Ted Van Pelt: https://www.flickr.com/photos/bantam10/5209157298 (CC BY 2.0 Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 41
Entwickler Doku Workflow
HTML PDF
Leser
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 42
21 Zielgruppen identifizieren
Entwickler Projektleiter
Fach- Architekt experten Produkt- manager
Tester Betrieb
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 43
Ausrichtung auf Zielgruppen
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 44
22 Single Source of Truth
Blog/Wiki
Präsentation Dokument
PDF Video, Podcast HTML E-Reader Papier
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld
WYSIWYG ABLAGE REDUNDANZEN
TEXTWÜSTE Smells
- HANDARBEIT TOTE DOKU
Doku ELFENBEINTURM
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 46
23 nur so viel wie nötig geringe Änderungsrate Zielgruppenbedürfnisse Feedback einpflegen
Pragmatik/Effektivität
Foto von PublicDomainPictures: https://pixabay.com/de/ansager-audio-schwarz-kassette-316584/ (CC0 Public Domain Lizenz)
Foto von Devanath: https://pixabay.com/de/bleistift-b%C3%BCro-design-kreative-1209544/ (CC0 Public Domain Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 47
Validierung
SanityChecks Broken Links PDFUnit
Foto von skeeze: https://pixabay.com/en/military-honor-guard-inspection-642639/ (CC0 Public Domain Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 48
24 Ausführbare Dokumentation
Ausführbare Tests Einbettung in Dokument Reportgenerierung
Foto von Wikimedia: https://commons.wikimedia.org/wiki/File%3A2014_W6N_-_France_vs_Italy_-_Christelle_Le_Duff_5780.jpg ( Creative Commons Attribution 3.0 Unported)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 49
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 50
25 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 51
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 52
26 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 53
Generierte Cypher- Regel [[architecture:UndefinedDependencies]] [source,cypher,role=constraint,requiresConcepts There must not be dependencies between Maven project which have not been defined. ---- Architektur- MATCH (p1:Maven:Project)-[:CREATES]->(:Artifact) definition (p2:Maven:Project)-[:CREATES]->(:Artifact) (t2)-[:DEPENDS_ON]->(t1) in PlantUML WHERE NOT (p1)-[:DEFINES_DEPENDENCY]->(p2) [[architecture:DefinedDependencies] RETURN [plantuml,role=concept] * ------[artifactId:xo.impl] as impl <<:Maven:Project>> [artifactId:xo.api] as api <<:Maven:Project>> [artifactId:xo.spi] as spi <<:Maven:Project>> impl -> api : Defines Dependency impl -> spi : Defines Dependency spi -> api : Defines Dependency ----
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 54
27 WYSIWYG ABLAGE REDUNDANZEN
TEXTWÜSTE Smells
- HANDARBEIT TOTE DOKU
Doku ELFENBEINTURM
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 55
Klassische Architekten Rolle
Foto von scottwebb: https://pixabay.com/en/toronto-architecture-skyscraper-1594940/ (CC0 Public Domain Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 56
28 Architekt/Senior Developer als Ratgeber/Mentor und Moderator
Foto von JESHOOTS: https://pixabay.com/de/warten-termin-zeitplan-zeit-eile-410328/ (CC0 Public Domain Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 57
Vorbereiten Planen Erinnern Delegieren Integrieren Prüfen
Dokumentation braucht einen Kümmerer
Foto von Berzin: https://pixabay.com/en/ambulance-doctor-students-game-2166079/ (CC0 Public Domain Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 58
29 WYSIWYG ABLAGE REDUNDANZEN
TEXTWÜSTE Smells
- HANDARBEIT TOTE DOKU
Doku ELFENBEINTURM
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 59
WYSIWYG Plain Text ABLAGE Documentation as Code REDUNDANZEN Generierung TEXTWÜSTE Mehr Grafiken HANDARBEIT Automatisierung TOTE DOKU Lebendige Dokument.
Zusammenfassung ELFENBEINTURM Kümmerer
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 60
30 Verschiedene Szenarien
Foto von nikidinov: https://pixabay.com/en/ballet-swan-lake-ballerina-dance-2124652/ (CC0 Public Domain Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 61
Szenario 1: Markdown, Pandoc, PlantUML, yEd
• Schreiben in Markdown in IDE (IntelliJ IDEA) inkl. Preview
• PDF-Erzeugung mit PanDoc über LaTex-Zwischenschritt inkl. Corporate Design
• UML-Diagramme mit PlantUML, Live-Ansicht/Export aus IDE
• andere Diagramme mit yEd, Export als *.png
• Stash/Bitbucket Server als Repo – rendert Markdown direkt in Weboberfläche – readme.md Verlinkungen auf wichtige Dokumente
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 62
31 Szenario 2: AsciiDoctor, Maven, PlantUML
• Erstellen AsciiDoc und PlantUML in IDE mit Preview
• Maven-Plugin zum Erzeugen des HTML/PDF
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 63
Szenario 3: Generierung aus Quellcode
• Quellcode parsen – Reflection – Spring Kontext – …
• in Unit-Test aus Klassen-Strukturen Diagramm-Markup erzeugen – z. B. PlantUML – als Text-Datei ablegen und in Markup-Dokumentation verlinken
• im Build-Prozess als Input für Markup-Konvertierung einlesen
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 64
32 Szenario 4: Schnittstellenbeschreibung
• Generierung aus WSDL, WADL, Swagger
• Einbindung in Build-Prozess
• Swagger2Markup
• JAX-RS Analyzer
• Spring REST Docs
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 65
Szenario 5: Ausführbare Dokumentation
• Quellcode-Struktur in Graph-Datenbank importieren
• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 66
33 Szenario 6: docToolchain
https://github.com/docToolchain/docToolchain
docToolchain is an implementation of the docs-as-code approach for software architecture. The basis of docToolchain is the philosophy that software documentation should be treated in the same way as code together with the arc42 template for software architecture.
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 67
Szenario 7: Wiki
CC BY-SA 3.0, https://de.wikipedia.org/wiki/Ward_Cunningham#/media/File:Ward_Cunningham_-_Commons-1.jpg
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 68
34 Zusammenarbeit
Verlinkung Review-/Redaktions-Prozess Prozess-Unterstützung Abbildung Workflow Erweiterung über Plugins Alles in einer Box!
Foto von makamuki0: https://pixabay.com/de/castellers-castells-h%C3%A4nde-ananas-921018/(CC0 Public Domain Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 69
Strukturiert? Plain-Text? Offlinefähigkeit? Versionierung? Code-Nähe? Automatisierung? Druckausgabe? Zielgruppen? Kontextwechsel
Schlund des Wiki
Foto von MartinStr: https://pixabay.com/de/krokodil-thailand-z%C3%A4hne-f%C3%BCtterung-225615/ (CC0 Public Domain Lizenz)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 70
35 Tasks Mentions
Kommentare Jira
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 71
Balsamiq Mockups
Gliffy (Diagramme, UML)
© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 72
36 ? ? ? ?Fragen ? ? ?
Orientation in Objects GmbH
Weinheimer Str. 68 ? 68309 Mannheim www.oio.de 73 [email protected] ?
Vielen Dank für Ihre Aufmerksamkeit !
Orientation in Objects GmbH
Weinheimer Str. 68 68309 Mannheim www.oio.de [email protected]
37