Kontinuierliche Architekturdokumentation im agilen Umfeld 3 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 5 Die 7 Sündender Architekturdokumentation

1

Orientation in Obj ects GmbH

Weinheimer Str. 6868309 Mannheim

[email protected]:

Lebendige

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


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

v on 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

Textverarbeitungsprogramme sind für technische Dokumentation

schlecht geeignet, ein Wiki auch nur bedingt. Anhand einigerFallbeispiele schauen wir uns an, wie man mit

Entwicklerwerkzeugen Dokumentation redundanzfrei erstellt und

pflegt, wie man sie validiert und in Teilen generieren oder sogar alsRegelwerk ausführen kann.

Die resultierenden Dokumente müssen natürlich jederzeit in

verschiedenen Formaten und für die jeweiligen Zielgruppen

angepasst erzeugt werden können. Ein effizienter Build-Prozess,dazu schlanke Dokumenten- und Grafikformate sowie eine

strukturierte Ablage der Quellen inklusive einheitlicherVersionierung, Historisierung und Vergleichbarkeit sind wichtige

Komponenten für Continuous Documentation und Documentation

as Code.

3

Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH 5

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)


Anforderungen

klären

Architektur

entwerfen

Architektur

bewerten

aus: Effektive

Softwarearchitekturen

(Gernot Starke)

Architektur

kommunizieren

War

um

dok

um

entier

en?

https://pixabay.com/en/fish-newspaper-food-russian-salted-224097/

https://pixabay.com/service/terms/

4


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)


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

https://github.com/thepracticaldev/orly-full-res/blob/master/notwritingdocs-big.png


5


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE


Foto von Antranias: https://pixabay.com/en/telescope-view-distant-binoculars-1201497/ (CC0 Public Domain Lizenz)

Textverarbeitung

Visio

Powerpoint

UML-Tools

https://pixabay.com/en/telescope-view-distant-binoculars-1201497/


6


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


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

7


AsciiDoc

14


Welcher Markup-Typ bin ich?

15

8


Einheitliche Dokumentenstruktur (z. B. arc42)

16


arc42 Templates

17

9


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE


Foto von UliSchu: https://pixabay.com/en/organization-register-folder-files-1205171/ (CC0 Public Domain Lizenz)

https://pixabay.com/en/organization-register-folder-files-1205171/


10


• 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)


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)

https://pixabay.com/de/unternehmer-start-start-up-karriere-696976/


https://pixabay.com/en/vault-business-bank-vault-bank-1144249/


11


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE


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)

https://pixabay.com/en/umbrellas-sea-holiday-summer-beach-921501/


12


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)


Schnittstellenbeschreibung generieren

https://pixabay.com/en/wind-turbine-energy-electricity-937715/


13


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE


Ein Bild sagt mehr als tausend Worte!

14


Quelle für Bilder/Grafiken

• Export aus UML-Modellen

• Manuelle Erstellung (Bildverarbeitung/Visualisierungsprogramme)

• Einbetten/Verlinken in Markup:

28

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

image::bild.png[Alternativtext]


Tools

… und Enterprise Architect, Magic Draw, …

yEd ist ein kostenloses

Visualisierungsprogramm

15


Diagramme als textuelle Beschreibung

30


"AsciiArt"

16


Online-

Tools


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)


17


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE


Agile Projekte

iterativ

kontinuierlichFoto von Unsplash: https://pixabay.com/de/fluss-bachlauf-bach-l%C3%A4ndlich-768654/ (CC0 Public Domain Lizenz)

https://pixabay.com/de/fluss-bachlauf-bach-l%C3%A4ndlich-768654/


18


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)


HTML

PDF

Leser

EntwicklerWorkflow

https://www.flickr.com/photos/bantam10/5209157298

https://creativecommons.org/licenses/by/2.0/

19


Ausrichtung auf Zielgruppen

38


Video, Podcast

Präsentation

Blog/Wiki

Dokument

PDFHTML

E-ReaderPapier

Single Sourceof Truth

20


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE


Pragmatik/Effektivität

nur so viel wie nötiggeringe ÄnderungsrateZielgruppenbedü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)

https://pixabay.com/de/bleistift-b%C3%BCro-design-kreative-1209544/


https://pixabay.com/de/ansager-audio-schwarz-kassette-316584/


21


Validierung

SanityChecks

Broken Links

PDFUnit

Foto von skeeze: https://pixabay.com/en/military-honor-guard-inspection-642639/ (CC0 Public Domain Lizenz)


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_Duf f_5780.jpg ( Creative Commons Attribution 3.0 Unported)

https://pixabay.com/en/military-honor-guard-inspection-642639/


https://commons.wikimedia.org/wiki/File:2014_W6N_-_France_vs_Italy_-_Christelle_Le_Duff_5780.jpg

https://en.wikipedia.org/wiki/Creative_Commons

22



23


Living Documentation


24


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 Dependencyimpl -> spi : Defines Dependencyspi -> 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]-(p2:Maven:Project)-[:CREATES]-

(t2)-[:DEPENDS_ON]->(t1)WHERE NOT

(p1)-[:DEFINES_DEPENDENCY

RETURN*

----


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

25


Klassische

Architekten

Rolle

Foto von scottwebb: https://pixabay.com/en/toronto-architecture-skyscraper-1594940/ (CC0 Public Domain Lizenz)


Architekt/Senior Developer als

Ratgeber/Mentor

und ModeratorFoto von JESHOOTS: https://pixabay.com/de/warten-termin-zeitplan-zeit-eile-410328/ (CC0 Public Domain Lizenz)

https://pixabay.com/en/toronto-architecture-skyscraper-1594940/


https://pixabay.com/de/warten-termin-zeitplan-zeit-eile-410328/


26


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)


Dok

u-Sm

ells

WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

https://pixabay.com/en/ambulance-doctor-students-game-2166079/


27


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


Verschiedene SzenarienFoto von nikidinov: https://pixabay.com/en/ballet-swan-lake-ballerina-dance-2124652/ (CC0 Public Domain Lizenz)

https://pixabay.com/en/ballet-swan-lake-ballerina-dance-2124652/


28


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

56


Szenario 1: User-Feedback

57

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

29


Szenario 2: AsciiDoctor, Maven, PlantUML

• Erstellen AsciiDoc und PlantUML in IDE mit Preview

• Maven-Plugin zum Erzeugen des HTML/PDF

58


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

30


Szenario 4: Schnittstellenbeschreibung

• Generierung aus WSDL, WADL, Swagger

• Einbindung in Build-Prozess

• Swagger2Markup

• JAX-RS Analyzer

• Spring REST Docs

60


Szenario 5: Ausführbare Dokumentation

• Quellcode-Struktur in Graph-Datenbank importieren

• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten

61

31



[email protected]

??

? ?

????

Fragen ?

62



[email protected]

Vielen Dank für Ihre

Aufmerksamkeit !

Documents

Kontinuierliche Architekturdokumentation im agilen Umfeld 3 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 5 Die 7 Sündender Architekturdokumentation