kontinuierliche architekturdokumentation im agilen umfeld · 2019-09-27 · szenario 1: markdown,...
TRANSCRIPT
1
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
Kontinuierliche
Architekturdokumentation
im agilen Umfeld
1.0
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 2
Die 7 Sünden der
Architekturdokumentation
Doku-Smells
Foto von jesperbkskov: https://pixabay.com/en/fish-newspaper-food-russian-salted-224097/ (CC0 Public Domain Lizenz)
2
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Ihr Sprecher
Architektur
Agile Softwareentwicklung
Codequalität
Trainer, Berater, Entwickler
Falk Sippach (@sippsack)
3
Co-Organisator
Co-Organisator
Commiter DukeCon
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 )
4
3
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Abstract
5
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.
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
Waru
m d
okum
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
Dokumentieren nervt
• Falsche Werkzeuge
• Dateiablage im Share-Laufwerk
• Redundanzen
• Textwüste
• Handarbeit
• Veraltet
• Liest sowieso keiner!
8
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
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
6
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 11
Hauptsache, du machst es
nicht mit Word!
http://www.machsmit.de/kampagne/motive_der_kampagne/index.php
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 12
Foto von Antranias: https://pixabay.com/en/telescope-view-distant-binoculars-1201497/ (CC0 Public Domain Lizenz)
Textverarbeitung
Visio
Powerpoint
UML-Tools
7
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Alternative Datenformate zu Textverarbeitung
13
Wikis
Mindmaps
Plain-Text
LaTex/DocBook
Richtext
Plain-Text, leicht lesbar, einfach
editierbar, automatisiert verarbeitbar
eingeschränkte Lesbarkeitkollaborativ
visuell,
kurz & knappAustauschformat
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
14
8
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
AsciiDoc
15
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Welcher Markup-Typ bin ich?
16
9
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Einheitliche Dokumentenstruktur (z. B. arc42)
17
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
arc42 Templates
18
10
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 19
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 20
Foto von UliSchu: https://pixabay.com/en/organization-register-folder-files-1205171/ (CC0 Public Domain Lizenz)
11
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 21
• 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)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 22
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)
12
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 23
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 24
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)
13
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 25
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)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 26
Schnittstellenbeschreibung generieren
14
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 27
interface DemoService {
String foobar();
}
class DemoServiceImpl implements DemoService {
@Override
public String foobar() {
return "demo";
}
}
enum State {
NEW, OPEN, APPROVED, IN_PROGRESS, FIXED
}
PlantUML+AsciiDocgenerieren
QuellcodeDB-SchemaUML-ModellKonfiguration
@startuml
interface DemoService
DemoService <|--
enum State {
NEW
OPEN
APPROVED
IN_PROGRESS
FIXED
}
@enduml
# Werte von State
* NEW
* OPEN
* APPROVED
* IN_PROGRESS
* FIXED
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 28
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
15
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 29
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:
30
![Alternativtext](bild.png "Bildtitel hier")
image::bild.png[Alternativtext]
16
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
B(u)ild-Tool?
31
Paint? Sicher nicht!
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 32
Tools
… und Visio, Enterprise Architect, Magic Draw, …
yEd ist ein kostenloses
Visualisierungsprogramm
17
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Diagramme als textuelle Beschreibung
33
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 34
"AsciiArt"
18
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 35
Online-
Tools
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 36
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
19
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 37
Agile Projekte
iterativ
kontinuierlichFoto von Unsplash: https://pixabay.com/de/fluss-bachlauf-bach-l%C3%A4ndlich-768654/ (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 38
Agile Teams brauchen nicht dokumentieren!
Häh?
Endlich ...
20
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 39http://agilemanifesto.org/background.jpg
Laufende Software
wichtiger als
ausführliche Dokumentation
Wer ist schuld?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Worauf das agile Manifest eigentlich abzielte …
40
Documentation through the
Software Development Lifecycle
http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm
21
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 41
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 42
HTML
Leser
EntwicklerDoku
Workflow
22
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Zielgruppen identifizieren
43
Projektleiter
Produkt-
manager
TesterBetrieb
Fach-
experten
Entwickler
Architekt
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Ausrichtung auf Zielgruppen
44
23
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Video, Podcast
Präsentation
Blog/Wiki
Dokument
PDFHTML
E-ReaderPapier
Single Sourceof Truth
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 46
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
24
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 47
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)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 48
Validierung
SanityChecks
Broken Links
PDFUnit
Foto von skeeze: https://pixabay.com/en/military-honor-guard-inspection-642639/ (CC0 Public Domain Lizenz)
25
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 49
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)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 50
26
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 51
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 52
27
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 53
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 54
Architektur-definition
in PlantUML
GenerierteCypher-
Regel
[[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
There must not be dependencies between Maven project which have not been defined.
----
MATCH
(p1:Maven:Project)-[:CREATES]->(:Artifact)
(p2:Maven:Project)-[:CREATES]->(:Artifact)
(t2)-[:DEPENDS_ON]->(t1)
WHERE NOT
(p1)-[:DEFINES_DEPENDENCY]->(p2)
RETURN
*
----
28
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 55
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 56
Klassische
Architekten
Rolle
Foto von scottwebb: https://pixabay.com/en/toronto-architecture-skyscraper-1594940/ (CC0 Public Domain Lizenz)
29
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 57
Architekt/Senior Developer als
Ratgeber/Mentor
und ModeratorFoto von JESHOOTS: https://pixabay.com/de/warten-termin-zeitplan-zeit-eile-410328/ (CC0 Public Domain Lizenz)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 58
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)
30
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 59
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 60
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
31
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 61
Verschiedene SzenarienFoto von nikidinov: https://pixabay.com/en/ballet-swan-lake-ballerina-dance-2124652/ (CC0 Public Domain Lizenz)
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
62
32
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
63
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
64
33
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
65
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
66
34
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Szenario 6: docToolchain
67
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.
https://github.com/docToolchain/docToolchain
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Szenario 7: Wiki
68
CC BY-SA 3.0, https://de.wikipedia.org/wiki/Ward_Cunningham#/media/File:Ward_Cunningham_-_Commons-1.jpg
35
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 69
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)
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 70
Schlund des Wiki
Strukturiert?
Plain-Text?
Offlinefähigkeit?
Versionierung?
Code-Nähe?
Automatisierung?
Druckausgabe?
Zielgruppen?
Kontextwechsel
Foto von MartinStr: https://pixabay.com/de/krokodil-thailand-z%C3%A4hne-f%C3%BCtterung-225615/ (CC0 Public Domain Lizenz)
36
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 71
TasksMentions
Kommentare Jira
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 72
Balsamiq Mockups
Gliffy (Diagramme, UML)
37
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
??
? ?
????
Fragen ?
73
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
Vielen Dank für Ihre
Aufmerksamkeit !