Kontinuierliche Architekturdokumentation Im Agilen Umfeld

Kontinuierliche Architekturdokumentation im agilen Umfeld

Orientation in Objects GmbH

Weinheimer Str. 68 68309 Mannheim

www.oio.de Version: 1.0 [email protected] Ihr Sprecher

Falk Sippach (@sippsack)

Trainer, Berater, Entwickler

Architektur Agile Softwareentwicklung Co-Organisator Codequalität

Feedback gern an: @sippsack, [email protected]

) Software Factory ) ) Object Rangers ) ) Competence Center)

• Schlüsselfertige Realisierung • Unterstützung laufender • Schulungen, Coaching, von Java Software Java Projekte Weiterbildungsberatung, Train & Solve-Programme • Individualsoftware • Perfect Match • Methoden, Standards und • Pilot- und Migrationsprojekte • Rent-a-team Tools für die Entwicklung • Sanierung von Software • Coaching on the project von offenen, unternehmens- • Software Wartung • Inhouse Outsourcing weiten Systemen

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.

Warum? Agil? Was? Wie?

Architektur Architektur bewerten entwerfen

Architektur kommunizieren aus: Effektive

Warum dokumentieren? Warum Softwarearchitekturen

© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 7 "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." Warum dokumentieren? Warum

"Die Architektur zu dokumentieren, ist der kritische, krönende Schritt zur Erschaffung."

Warum dokumentieren? Warum Aus: Software Architecture Documentation in Practice von Bachmann, Bass

© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 9 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 10 Gründe für eine Architektur-Dokumentation

Entwurfsunterstützung

Kommunikation

Bewertbarkeit

Frage nach Warum

Neue Mitarbeiter

Warum? Agil? Was? Wie?

rückwärts! Agil Agil dokumentieren?

Häh?

Laufende Software wichtiger als ausführliche Dokumentation

http://agilemanifesto.org/background.jpg © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 15 Worauf das agile Manifest eigentlich abzielte …

Documentation through the Software Development Lifecycle

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

"Who needs an Architect?"

iterativ kontinuierlich

Continuous Documentation

Quellcode verlinken Platzhalter einbetten Single Source of Truth

WSDL, Swagger DB-Schema Annotationen JavaDoc

SanityChecks Broken Links PDFUnit

Ausführbare Tests Einbettung in Dokument Reportgenerierung

© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 26 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 27 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 28 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 29 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 30 Kontinuierliche Architekturdokumentation

Warum? Agil? Was? Wie?

Inhalt Was dokumentieren? Was

... die wesentlich sind, damit Systeme ihren Anforderungen genügen! ... die man nicht mehr leicht losbekommt!

Zusammenarbeit zur Laufzeit

Integration in techn. Infrastruktur

Technische Konzepte

Wichtige Entscheidungen

Pragmatik/Effektivität

Warum? Agil? Was? Wie?

Prozess Werkzeugkette Wie dokumentieren? Wie

Doku-

Wie dokumentieren? Wie Grafiken? Format?

Doku-

Wie dokumentieren? Wie Grafiken? Format?

Doku-

Wie dokumentieren? Wie Grafiken? Format?

Präsentation Dokument

PDF Video, Podcast HTML E-Reader Papier

Doku-

Wie dokumentieren? Wie Grafiken? Format?

Entwickler Projektleiter

Fach- Architekt experten Produkt- manager

Tester Betrieb

• Inhalte pro Zielgruppe festlegen • möglichst ein zentrales Dokument • (automatisiert) verschiedene Ausgabedokumente generieren

Doku-

Wie dokumentieren? Wie Grafiken? Format?

• Plain-Text • Entwicklungsumgebung • Kommandozeilen- werkzeuge • Versionsverwaltung

© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 49 Code-Nähe Ablage im Repo Versionier-/diffbar Synchrone Auslieferung Offlinefähig Teil des Build-Prozess Generierung Automatisierung Flexible Ausgabeformate

Documentation as Code

HTML PDF

Leser

Plain-Text, leicht lesbar, einfach editierbar, automatisiert verarbeitbar

Plain-Text

kollaborativ eingeschränkte Lesbarkeit

Wikis LaTex/DocBook kurz & knapp Austauschformat Mindmaps Richtext

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

• JavaDoc/Annotations

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

• Schnittstellenbeschreibung (WSDL, Swagger, WADL)

• DB-Schema (SchemaCrawler)

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

Doku-

Wie dokumentieren? Wie Grafiken? Format?

yEd ist ein kostenloses Visualisierungsprogramm

… und Enterprise Architect, Magic Draw, …

• UML-Modelle • Bildverarbeitung/Visualisierungsprogramme

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

• Textuelle Beschreibung (ASCII-Art)

© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 61 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 62 Generation Plain-Text Diagramme

Quellen:

Sourcecode DB-Schema XML-Modell

Muss nicht aktuell gehalten werden!

© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 63 © Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 64 Ziel- gruppen? Werkzeuge? Struktur? Medien?

Doku-

Wie dokumentieren? Wie Grafiken? Format?

• 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

"Generiertes PDF stellt alles bisherige "Entwickler finden es in den Schatten." klasse, Leser innerhalb der Firma: finden das "… fast alles ist generierte PDF sehr gut leicht versionier- und hübsch." und diffbar"

"… jeder Entwickler "Nie wieder anders! kann ändern…" Ich bin voll überzeugt."

• Erstellen AsciiDoc und PlantUML in IDE mit Preview

• Maven-Plugin zum Erzeugen des HTML/PDF

Demo

• 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

• Generierung aus WSDL, WADL, Swagger

• Einbindung in Build-Prozess

• Swagger2Markup • JAX-RS Analyzer • Spring REST Docs Demo

• Quellcode-Struktur in Graph-Datenbank importieren

• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten

Demo

Doku-

Wie dokumentieren? Wie Grafiken? Format?

Verlinkung Review-/Redaktions-Prozess Prozess-Unterstützung Abbildung Workflow Erweiterung über Plugins Alles in einer Box!

© Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 75 Strukturiert? Plain-Text? Offlinefähigkeit? Versionierung? Code-Nähe? Automatisierung? Druckausgabe? Zielgruppen? Kontextwechsel

Schlund des Wiki

Kommentare Jira

Gliffy (Diagramme, UML)

Orientation in Objects GmbH

Weinheimer Str. 68 ? 68309 Mannheim www.oio.de 79 [email protected] Vielen Dank für Ihre Aufmerksamkeit !

Orientation in Objects GmbH

Weinheimer Str. 68 68309 Mannheim www.oio.de [email protected]