kontinuierliche architekturdokumentation im agilen umfeld · • uml-diagramme mit plantuml,...
TRANSCRIPT
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
Ihr Sprecher
Architektur
Agile Softwareentwicklung
Codequalität
Trainer, Berater, Entwickler
Falk Sippach (@sippsack)
2
Co-Organisator
Gern Feedback an: @sippsack, [email protected]
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.
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 5
Warum? Agil? Was? Wie?
Kontinuierliche Architekturdokumentation
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 6
Warum?
Kontinuierliche Architekturdokumentation
Agil? Was? Wie?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 7
Anforderungenklären
Architekturentwerfen
Architekturbewerten
aus: Effektive
Softwarearchitekturen
Architektur kommunizieren
Waru
m d
okum
entier
en?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 8
Waru
m d
okum
entier
en?
"Die Architektur zu dokumentieren,
ist der kritische, krönende Schritt
zur Erschaffung."
"… dass auch eine perfekte
Architektur nutzlos bleibt,
wenn sie nicht verstanden wird …"
Aus: Software Architecture Documentation in Practice von Bachmann, Bass
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 9
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Gründe für eine Architektur-Dokumentation
10
Neue Mitarbeiter
Entwurfsunterstützung
Frage nach Warum
Bewertbarkeit
Kommunikation
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 11
Warum?
Kontinuierliche Architekturdokumentation
Agil? Was? Wie?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 12
Agi
l dok
um
entier
en?
Scrum ist "murcS"
rückwärts!
"Wenn ein Projekt
den Bach runter geht,
dann nennt man das wohl
Wasserfall."
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 13
Agile Teams brauchen nicht dokumentieren!
Häh?
Endlich ...
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 14http://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 …
15
Documentation through the
Software Development Lifecycle
http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 16
Agile Methoden
kennen keinen
Architekten!
"Who needs
an Architect?"
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 17
Architekt als
Ratgeber/Mentor
und Moderator
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 18
Dokumentation braucht einen
Kümmerer
Vorbereiten
Planen
Erinnern
Delegieren
Integrieren
Prüfen
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 19
Agile Projekte
iterativ
kontinuierlich
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 20
Continuous
Documentation
Anpassen
Reviewen
Nachbessern
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 21
Redundanzen
vermeidbar?
Quellcode verlinken
Platzhalter einbetten
Single Source of Truth
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 22
Inhalte
generierbar?
WSDL, Swagger
DB-Schema
Annotationen
JavaDoc
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 23
Schnittstellenbeschreibung
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 24
Validierung
SanityChecks
Broken Links
PDFUnit
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 25
Ausführbare Dokumentation
Ausführbare Tests
Einbettung in Dokument
Reportgenerierung
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 26
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 27
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 28
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 29
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 30
Warum?
Kontinuierliche Architekturdokumentation
Agil? Was? Wie?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 31
Was
dok
um
entier
en?
Inhalt
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Was ist nochmal Architektur?
32
fundamentale
Strukturen,
Konzepte,
Entscheidungen
und Lösungsansätze
... die wesentlich sind, damit Systeme
ihren Anforderungen genügen!
... die man nicht mehr leicht losbekommt!
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Was gehört in die Architektur-Dokumentation?
33
Bausteine und Schnittstellen
Zusammenarbeit zur Laufzeit
Integration in techn. Infrastruktur
Technische Konzepte
Wichtige Entscheidungen
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 34
Pragmatik/Effektivität
nur so viel wie nötig,
wenig Änderungen,
Zielgruppenbedürfnisse,
Feedback einpflegen
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 35
Warum?
Kontinuierliche Architekturdokumentation
Agil? Was? Wie?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 36
Wie
dok
um
entier
en?
Prozess Werkzeugkette
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 37
Wie
dok
um
entier
en?
Struktur?Werkzeuge?
Medien?
Doku-Format?Grafiken?
Ziel-gruppen?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 38
Wie
dok
um
entier
en?
Struktur?Werkzeuge?
Medien?
Doku-Format?Grafiken?
Ziel-gruppen?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 39
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
arc42 Templates
40
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 41
Wie
dok
um
entier
en?
Struktur?Werkzeuge?
Medien?
Doku-Format?Grafiken?
Ziel-gruppen?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Video, Podcast
Präsentation
Blog/Wiki
Dokument
PDFHTML
E-ReaderPapier
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 43
Wie
dok
um
entier
en?
Struktur?Werkzeuge?
Medien?
Doku-Format?Grafiken?
Ziel-gruppen?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Zielgruppen identifizieren
44
Projektleiter
Produkt-
manager
TesterBetrieb
Fach-
experten
Entwickler
Architekt
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Braucht jeder alles?
• Inhalte pro Zielgruppe festlegen
• möglichst ein zentrales Dokument
• (automatisiert) verschiedene Ausgabedokumente generieren
45
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 46
Wie
dok
um
entier
en?
Struktur?Werkzeuge?
Medien?
Doku-Format?Grafiken?
Ziel-gruppen?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 47
Hauptsache, du machst es
nicht mit Word!
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 48
• Plain-Text
• Entwicklungsumgebung
• Kommandozeilen-
werkzeuge
• Versionsverwaltung
Unser täglich Entwickler-Brot:
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 49
Documentation as Code
Code-Nähe
Ablage im Repo
Versionier-/diffbar
Synchrone Auslieferung
Offlinefähig
Teil des Build-Prozess
Generierung
Automatisierung
Flexible Ausgabeformate
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 50
HTML
Leser
EntwicklerWorkflow
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Alternative Datenformate
51
Wikis
Mindmaps
Plain-Text
LaTex/DocBook
Richtext
Plain-Text, leicht lesbar, einfach
editierbar, automatisiert verarbeitbar
eingeschränkte Lesbarkeitkollaborativ
kurz & knapp
Austauschformat
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
52
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
AsciiDoc
53
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Markup generieren
• JavaDoc/Annotations
• Enumwerte/Zustandsübergänge (Enum-Werte)
• Schnittstellenbeschreibung (WSDL, Swagger, WADL)
• DB-Schema (SchemaCrawler)
54
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 55
Tools
… und Sublime, Atom, IntelliJ IDEA, Eclipse, …
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 56
Wie
dok
um
entier
en?
Struktur?Werkzeuge?
Medien?
Doku-Format?Grafiken?
Ziel-gruppen?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 57
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 58
Tools
… und Enterprise Architect, Magic Draw, …
yEd ist ein kostenloses
Visualisierungsprogramm
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Quelle für Bilder/Grafiken
• UML-Modelle
• Bildverarbeitung/Visualisierungsprogramme
• Textuelle Beschreibung (ASCII-Art)
59
![Alternativtext](bild.png "Bildtitel hier")
image::bild.png[Alternativtext]
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 60
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 61
Quellen:
Sourcecode
DB-Schema
XML-Modell
Muss nicht aktuell gehalten werden!
Generation Plain-Text Diagramme
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 62
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 63
Wie
dok
um
entier
en?
Struktur?Werkzeuge?
Medien?
Doku-Format?Grafiken?
Ziel-gruppen?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 64
Verschiedene Szenarien
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
65
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH
Szenario 1: User-Feedback
66
"Entwickler finden es
klasse, Leser innerhalb
der Firma: finden das
generierte PDF sehr gut
und hübsch."
"… fast alles ist
leicht versionier-
und diffbar"
"… jeder Entwickler
kann ändern…""Nie wieder anders!
Ich bin voll überzeugt."
"Generiertes PDF
stellt alles bisherige
in den Schatten."
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
67
Demo
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
68
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
69
Demo
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
70
Demo
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 71
Wie
dok
um
entier
en?
Struktur?Werkzeuge?
Medien?
Doku-Format?Grafiken?
Ziel-gruppen?
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 72
Wiki
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 73
Zusammenarbeit
Verlinkung
Review-Prozess
Prozess-Unterstützung
Abbildung Workflow
Erweiterung über Plugins
Alles in einer Box!
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 74
Schlund des Wiki
Strukturiert?
Plain-Text?
Offlinefähigkeit?
Versionierung?
Code-Nähe?
Automatisierung?
Druckausgabe?
Zielgruppen?
Kontextwechsel
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 75
TasksMentions
Kommentare Jira
Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 76
Balsamiq Mockups
Gliffy (Diagramme, UML)
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
? ?
??
?Fragen ?
77
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
Vielen Dank für Ihre
Aufmerksamkeit !