Embed Size (px)
Citation preview
1
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
Sieben Sünden der
Architekturdokumentation
1.0
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Ihr Sprecher
Architektur
Agile Softwareentwicklung
Codequalität
Trainer, Berater, Entwickler
Falk Sippach (@sippsack)
2
Feedback gern an: @sippsack, [email protected]
Co-Organisator
2
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Java, XML und Open Source seit 1998
) Competence Center)) Object Rangers )
• Schulungen, Coaching,
Weiterbildungsberatung,
Train & Solve-Programme
• Methoden, Standards und
Tools für die Entwicklung
von offenen, unternehmens-
weiten Systemen
• Unterstützung laufender
Java Projekte
• Perfect Match
• Rent-a-team
• Coaching on the project
• Inhouse Outsourcing
• Schlüsselfertige Realisierung
von Java Software
• Individualsoftware
• Pilot- und Migrationsprojekte
• Sanierung von Software
• Software Wartung
) Software Factory )
3
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Abstract
4
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. In diesem Vortrag wollen wir
uns anschauen, wie aufbauend auf bestehenden Tools
und Textformaten eine möglichst redundanzfreie
Dokumentation erstellt und für verschiedene
Zielgruppen in ansprechenden Formaten ausgeliefert
werden kann. Es wird dabei um Begriffe wie Continuous
Documentation und Documentation as Code gehen.
3
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 5
Die 7 technischen Sünden der
Architekturdokumentation
Doku-Smells
Foto von jesperbkskov: https://pixabay.com/en/fish-newspaper-food-russian-salted-224097/ (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 6
Anforderungen
klären
Architektur
entwerfen
Architektur
bewerten
aus: Effektive
Softwarearchitekturen
(G. Starke + P. Hruschka)
Architektur
kommunizieren
War
um
dok
um
entier
en?
4
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Gründe für eine Architektur-Dokumentation
7
Neue Mitarbeiter
Entwurfsunterstützung
Frage nach Warum
Bewertbarkeit
Kommunikation
Grafik von The Practical Dev: https://github.com/thepracticaldev/orly-full-res/blob/master/notwritingdocs-big.png (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 8
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
5
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 9
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 10
Hauptsache, du machst es
nicht mit Word!
6
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 11
Foto von Antranias: https://pixabay.com/en/telescope-view-distant-binoculars-1201497/ (CC0 Public Domain Lizenz)
Textverarbeitung
Visio
Powerpoint
UML-Tools
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Alternative Datenformate zu Textverarbeitung
12
Wikis
Mindmaps
Plain-Text
LaTex/DocBook
Richtext
Plain-Text, leicht lesbar, einfach
editierbar, automatisiert verarbeitbar
eingeschränkte Lesbarkeitkollaborativ
visuell,
kurz & knappAustauschformat
7
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
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
13
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
AsciiDoc
14
8
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Welcher Markup-Typ bin ich?
15
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Einheitliche Dokumentenstruktur (z. B. arc42)
16
9
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
arc42 Templates
17
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 18
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
10
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 19
Foto von UliSchu: https://pixabay.com/en/organization-register-folder-files-1205171/ (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 20
• Plain-Text
• Entwicklungs-
umgebung
• Kommandozeilen-
werkzeuge
• Versions-
verwaltung
Unser täglich Entwickler-Brot:
Foto von geralt: https://pixabay.com/de/unternehmer-start-start-up-karriere-696976/ (CC0 Public Domain Lizenz)
11
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 21
Documentation as Code
Code-Nähe
Ablage im Repo
Versionier-/diffbar
Synchrone Auslieferung
Offlinefähig
Teil des Build-Prozess
Generierung
Automatisierung
Flexible Ausgabeformate
Foto von ahobbit: https://pixabay.com/en/vault-business-bank-vault-bank-1144249/ (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 22
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
12
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 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)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 24
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)
13
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 25
Schnittstellenbeschreibung generieren
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 26
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
14
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 27
Ein Bild sagt mehr als tausend Worte!
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Quelle für Bilder/Grafiken
• Export aus UML-Modellen
• Manuelle Erstellung (Bildverarbeitung/Visualisierungsprogramme)
• Einbetten/Verlinken in Markup:
28
image::bild.png[Alternativtext]
15
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
B(u)ild-Tool?
29
Paint? Sicher nicht!
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 30
Tools
… und Visio, Enterprise Architect, Magic Draw, …
yEd ist ein kostenloses
Visualisierungsprogramm
16
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Diagramme als textuelle Beschreibung
31
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 32
"AsciiArt"
17
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 33
Online-
Tools
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 34
Generation Plain-Text-Diagramme
Quellen:
Sourcecode
DB-Schema
XML-Modell
Foto von herbert2512: https://pixabay.com/en/steam-engine-toys-flywheel-drive-1592908/ (CC0 Public Domain Lizenz)
18
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 35
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 36
Agile Projekte
iterativ
kontinuierlichFoto von Unsplash: https://pixabay.com/de/fluss-bachlauf-bach-l%C3%A4ndlich-768654/ (CC0 Public Domain Lizenz)
19
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 37
Continuous
Documentation
Automatisiert erstellen
Regelmässig ergänzen
Reviewen
Nachbessern
Foto von Ted Van Pelt: https://www.flickr.com/photos/bantam10/5209157298 (CC BY 2.0 Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 38
HTML
Leser
EntwicklerWorkflow
20
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Ausrichtung auf Zielgruppen
39
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Video, Podcast
Präsentation
Blog/Wiki
Dokument
PDFHTML
E-ReaderPapier
Single Sourceof Truth
21
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 41
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 42
Pragmatik/Effektivität
nur so viel wie nötig
geringe Änderungsrate
Zielgruppenbedürfnisse
Feedback einpflegen
Foto von Devanath: https://pixabay.com/de/bleistift-b%C3%BCro-design-kreative-1209544/ (CC0 Public Domain Lizenz)
Foto von PublicDomainPictures: https://pixabay.com/de/ansager-audio-schwarz-kassette-316584/ (CC0 Public Domain Lizenz)
22
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 43
Validierung
SanityChecks
Broken Links
PDFUnit
Foto von skeeze: https://pixabay.com/en/military-honor-guard-inspection-642639/ (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 44
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)
23
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 45
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 46
24
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 47
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 48
25
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 49
[[architecture:DefinedDependencies]
[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
----
[[architecture:UndefinedDependencies]]
[source,cypher,role=constraint,requiresConcepts="archit
ecture:DefinedDependencies"]
.There must not be dependencies between Maven
project which have not been defined.
----
MATCH
(p1:Maven:Project)-[:CREATES]->(:Artifact)-
[:CONTAINS]->(t1:Type),
(p2:Maven:Project)-[:CREATES]->(:Artifact)-
[:CONTAINS]->(t2:Type),
(t2)-[:DEPENDS_ON]->(t1)
WHERE NOT
(p1)-[:DEFINES_DEPENDENCY]->(p2)
RETURN
*
----
Architekturdefinition in PlantUML,
eingebettet in Asciidoc
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 50
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
26
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 51
Klassische
Architekten
Rolle
Foto von scottwebb: https://pixabay.com/en/toronto-architecture-skyscraper-1594940/ (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 52
Architekt/Senior Developer als
Ratgeber/Mentor
und ModeratorFoto von JESHOOTS: https://pixabay.com/de/warten-termin-zeitplan-zeit-eile-410328/ (CC0 Public Domain Lizenz)
27
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 53
Dokumentation braucht einen
Kümmerer
Vorbereiten
Planen
Erinnern
Delegieren
Integrieren
Prüfen
Foto von Berzin: https://pixabay.com/en/ambulance-doctor-students-game-2166079/ (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 54
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
28
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 55
Zusa
mm
enfa
ssung
WYSIWYG Plain Text
REDUNDANZEN Generierung
HANDARBEIT Automatisierung
ABLAGE Documentation as Code
TOTE DOKU Lebendige Dokument.
ELFENBEINTURM Kümmerer
TEXTWÜSTE Mehr Grafiken
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 56
Verschiedene SzenarienFoto von nikidinov: https://pixabay.com/en/ballet-swan-lake-ballerina-dance-2124652/ (CC0 Public Domain Lizenz)
29
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
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
57
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Szenario 2: AsciiDoctor, Maven, PlantUML
• Erstellen AsciiDoc und PlantUML in IDE mit Preview
• Maven-Plugin zum Erzeugen des HTML/PDF
58
30
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
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
59
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Szenario 4: Schnittstellenbeschreibung
• Generierung aus WSDL, WADL, Swagger
• Einbindung in Build-Prozess
• Swagger2Markup
• JAX-RS Analyzer
• Spring REST Docs
60
31
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Szenario 5: Ausführbare Dokumentation
• Quellcode-Struktur in Graph-Datenbank importieren
• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten
61
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
??
? ?
????
Fragen ?
62
32
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
Vielen Dank für Ihre
Aufmerksamkeit !
![[NOTIZBUCH MASCHINEN, KYBERNETIK, NETZE] · Das regenerative Wissen und die visuelle Evidenz der Geometrie Diagramme von Dynamik / dynamische Diagramme Kurvendiagramme Das Diagrammatische](https://img.pdfslide.org/doc/110x75/5e074e89ea34835b17489450/notizbuch-maschinen-kybernetik-netze-das-regenerative-wissen-und-die-visuelle.jpg)
