Lebendige Architektur- Dokumentation - kontinuierlich und ......• UML-Diagramme mit PlantUML, Live-Ansicht/Export aus IDE • andere Diagramme mit yEd, Export als *.png • Stash/Bitbucket

Orientation in Objects GmbH

Weinheimer Str. 68

68309 Mannheim

www.oio.de

[email protected]:

Lebendige Architektur-

Dokumentation -

kontinuierlich und effizient

1.0

Lebendige Architektur-Dokumentation - kontinuierlich und effizient© Orientation in Objects GmbH

Ihr Sprecher

Architektur

Agile Softwareentwicklung

Codequalität

Trainer, Berater, Entwickler

Falk Sippach (@sippsack)

2

Co-Organisator

Feedback gern 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.

Lebendige Architektur-Dokumentation - kontinuierlich und effizient© 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?


"In software, there is always architecture.

You can’t have no architecture."

"But with it’s documentation, there are

two options: you can have one or not."

"If you have one, there are two options:

the documentation matches with the real

architecture or not."

Waru

m d

okum

entier

en?

http://techblog.kontext-e.de/keeping-architecture-and-doc-in-sync/


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

11

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

Lebendige Architektur-Dokumentation - kontinuierlich und effizient© Orientation in Objects GmbH 15http://agilemanifesto.org/background.jpg

Laufende Software

wichtiger als

ausführliche Dokumentation

Wer ist schuld?


Worauf das agile Manifest eigentlich abzielte …

16

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

Automatisiert erstellen

Regelmässig ergänzen

Reviewen

Nachbessern


Redundanzen

vermeiden

Quellcode verlinken

Platzhalter einbetten

Single Source of Truth


Inhalte

generieren

WSDL, Swagger

DB-Schema

Annotationen

JavaDoc


Schnittstellenbeschreibung generieren


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?

33

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?

34

Bausteine und Schnittstellen

Zusammenarbeit zur Laufzeit

Integration in techn. Infrastruktur

Technische Konzepte

Wichtige Entscheidungen


Pragmatik/Effektivität

nur so viel wie nötig

geringe Änderungsrate

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

41


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Video, Podcast

Präsentation

Blog/Wiki

Dokument

PDFHTML

E-ReaderPapier

Single Sourceof Truth


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Zielgruppen identifizieren

45

Projektleiter

Produkt-

manager

TesterBetrieb

Fach-

experten

Entwickler

Architekt


Braucht jeder alles?

• Inhalte pro Zielgruppe festlegen

• möglichst ein zentrales Dokument (Single Source of Truth)

• (automatisiert) verschiedene Ausgabedokumente generieren

46


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 zu Textverarbeitung

52

Wikis

Mindmaps

Plain-Text

LaTex/DocBook

Richtext

Plain-Text, leicht lesbar, einfach

editierbar, automatisiert verarbeitbar

eingeschränkte Lesbarkeitkollaborativ

visuell,

kurz & knappAustauschformat


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

53


AsciiDoc

54


Welcher Markup-Typ bin ich?

55


Tools für Markup-Sprachen

56

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


Markup generieren

• aus JavaDoc/Annotations

• aus Enumwerten (Zustandsübergänge)

• Schnittstellenbeschreibung (WSDL, Swagger, WADL)

• DB-Schema (SchemaCrawler)

57


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?



Quelle für Bilder/Grafiken

• Export aus UML-Modellen

• Manuelle Erstellung (Bildverarbeitung/Visualisierungsprogramme)

• Einbetten/Verlinken in Markup:

60

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

image::bild.png[Alternativtext]


Tools

… und Visio, Enterprise Architect, Magic Draw, …

yEd ist ein kostenloses

Visualisierungsprogramm


Diagramme als textuelle Beschreibung

• viele Formate (PlantUML, ditaa, …)

• Einbetten in Markup-Dokumente:

62


"AsciiArt"


Online-

Tools


Generation Plain-Text Diagramme

Nie mehr aktuell halten müssen!

Quellen:

Sourcecode

DB-Schema

XML-Modell


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

68


Szenario 1: User-Feedback

69

"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

70

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

71


Szenario 4: Schnittstellenbeschreibung

• Generierung aus WSDL, WADL, Swagger

• Einbindung in Build-Prozess

• Swagger2Markup

• JAX-RS Analyzer

• Spring REST Docs

72

Demo


Szenario 5: Ausführbare Dokumentation

• Quellcode-Struktur in Graph-Datenbank importieren

• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten

73

Demo


Wie

dok

um

entier

en?

Struktur?Werkzeuge?

Medien?


Ziel-gruppen?


Wiki


Zusammenarbeit

Verlinkung

Review-/Redaktions-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 ?

80


Weinheimer Str. 68

68309 Mannheim

www.oio.de

[email protected]

Vielen Dank für Ihre

Aufmerksamkeit !

Documents

Lebendige Architektur- Dokumentation - kontinuierlich und ......• UML-Diagramme mit PlantUML, Live-Ansicht/Export aus IDE • andere Diagramme mit yEd, Export als *.png • Stash/Bitbucket