Kontinuierliche Architekturdokumentation im agilen Umfeld · • UML-Diagramme mit PlantUML,...

Orientation in Objects GmbH

Weinheimer Str. 68

68309 Mannheim

www.oio.de

[email protected]:

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]


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


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


Warum?


Agil? Was? Wie?


Anforderungenklären

Architekturentwerfen

Architekturbewerten

aus: Effektive

Softwarearchitekturen

Architektur kommunizieren

Waru

m d

okum

entier

en?


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


Gründe für eine Architektur-Dokumentation

10

Neue Mitarbeiter

Entwurfsunterstützung

Frage nach Warum

Bewertbarkeit

Kommunikation


Warum?


Agil? Was? Wie?


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."


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?


Worauf das agile Manifest eigentlich abzielte …

15

Documentation through the

Software Development Lifecycle

http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm


Agile Methoden

kennen keinen

Architekten!

"Who needs

an Architect?"


Architekt als

Ratgeber/Mentor

und Moderator


Dokumentation braucht einen

Kümmerer

Vorbereiten

Planen

Erinnern

Delegieren

Integrieren

Prüfen


Agile Projekte

iterativ

kontinuierlich


Continuous

Documentation

Anpassen

Reviewen

Nachbessern


Redundanzen

vermeidbar?

Quellcode verlinken

Platzhalter einbetten

Single Source of Truth


Inhalte

generierbar?

WSDL, Swagger

DB-Schema

Annotationen

JavaDoc


Schnittstellenbeschreibung


Validierung

SanityChecks

Broken Links

PDFUnit


Ausführbare Dokumentation

Ausführbare Tests

Einbettung in Dokument

Reportgenerierung


Warum?


Agil? Was? Wie?


Was

dok

um

entier

en?

Inhalt


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!


Was gehört in die Architektur-Dokumentation?

33

Bausteine und Schnittstellen

Zusammenarbeit zur Laufzeit

Integration in techn. Infrastruktur

Technische Konzepte

Wichtige Entscheidungen


Pragmatik/Effektivität

nur so viel wie nötig,

wenig Änderungen,

Zielgruppenbedürfnisse,

Feedback einpflegen


Warum?


Agil? Was? Wie?


Wie

dok

um

entier

en?

Prozess Werkzeugkette


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?

Doku-Format?Grafiken?

Ziel-gruppen?


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


arc42 Templates

40


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Video, Podcast

Präsentation

Blog/Wiki

Dokument

PDFHTML

E-ReaderPapier


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Zielgruppen identifizieren

44

Projektleiter

Produkt-

manager

TesterBetrieb

Fach-

experten

Entwickler

Architekt


Braucht jeder alles?

• Inhalte pro Zielgruppe festlegen

• möglichst ein zentrales Dokument

• (automatisiert) verschiedene Ausgabedokumente generieren

45


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Hauptsache, du machst es

nicht mit Word!


• Plain-Text

• Entwicklungsumgebung

• Kommandozeilen-

werkzeuge

• Versionsverwaltung

Unser täglich Entwickler-Brot:


Documentation as Code

Code-Nähe

Ablage im Repo

Versionier-/diffbar

Synchrone Auslieferung

Offlinefähig

Teil des Build-Prozess

Generierung

Automatisierung

Flexible Ausgabeformate


HTML

PDF

Leser

EntwicklerWorkflow


Alternative Datenformate

51

Wikis

Mindmaps

Plain-Text

LaTex/DocBook

Richtext

Plain-Text, leicht lesbar, einfach

editierbar, automatisiert verarbeitbar

eingeschränkte Lesbarkeitkollaborativ

kurz & knapp

Austauschformat


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


AsciiDoc

53


Markup generieren

• JavaDoc/Annotations

• Enumwerte/Zustandsübergänge (Enum-Werte)

• Schnittstellenbeschreibung (WSDL, Swagger, WADL)

• DB-Schema (SchemaCrawler)

54


Tools

… und Sublime, Atom, IntelliJ IDEA, Eclipse, …


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Tools

… und Enterprise Architect, Magic Draw, …

yEd ist ein kostenloses

Visualisierungsprogramm


Quelle für Bilder/Grafiken

• UML-Modelle

• Bildverarbeitung/Visualisierungsprogramme

• Textuelle Beschreibung (ASCII-Art)

59

![Alternativtext](bild.png "Bildtitel hier")

image::bild.png[Alternativtext]


Quellen:

Sourcecode

DB-Schema

XML-Modell

Muss nicht aktuell gehalten werden!

Generation Plain-Text Diagramme


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Verschiedene Szenarien


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


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."


Szenario 2: AsciiDoctor, Maven, PlantUML

• Erstellen AsciiDoc und PlantUML in IDE mit Preview

• Maven-Plugin zum Erzeugen des HTML/PDF

67

Demo


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


Szenario 4: Schnittstellenbeschreibung

• Generierung aus WSDL, WADL, Swagger

• Einbindung in Build-Prozess

• Swagger2Markup

• JAX-RS Analyzer

• Spring REST Docs

69

Demo


Szenario 5: Ausführbare Dokumentation

• Quellcode-Struktur in Graph-Datenbank importieren

• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten

70

Demo


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Wiki


Zusammenarbeit

Verlinkung

Review-Prozess

Prozess-Unterstützung

Abbildung Workflow

Erweiterung über Plugins

Alles in einer Box!


Schlund des Wiki

Strukturiert?

Plain-Text?

Offlinefähigkeit?

Versionierung?

Code-Nähe?

Automatisierung?

Druckausgabe?

Zielgruppen?

Kontextwechsel


TasksMentions

Kommentare Jira


Balsamiq Mockups

Gliffy (Diagramme, UML)


Weinheimer Str. 68

68309 Mannheim

www.oio.de

[email protected]

? ?

??

?Fragen ?

77


Weinheimer Str. 68

68309 Mannheim

www.oio.de

[email protected]

Vielen Dank für Ihre

Aufmerksamkeit !

Kontinuierliche Architekturdokumentation im agilen Umfeld · • UML-Diagramme mit PlantUML,...

Documents

Transcript of Kontinuierliche Architekturdokumentation im agilen Umfeld · • UML-Diagramme mit PlantUML,...