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

Orientation in Objects GmbH

Weinheimer Str. 68

68309 Mannheim

www.oio.de

info@oio.deVersion:

Kontinuierliche

Architekturdokumentation

im agilen Umfeld

Kontinuierliche Architekturdokumentation im agilen Umfeld© Orientation in Objects GmbH

Ihr Sprecher

Architektur

Agile Softwareentwicklung

Codequalität

Trainer, Berater, Entwickler

Falk Sippach (@sippsack)

Co-Organisator

Gern Feedback an: @sippsack, falk.sippach@oio.de

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 )

Abstract

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

entier

"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

Neue Mitarbeiter

Entwurfsunterstützung

Frage nach Warum

Bewertbarkeit

Kommunikation

Warum?

Agil? Was? Wie?

entier

Scrum ist "murcS"

rückwärts!

"Wenn ein Projekt

den Bach runter geht,

dann nennt man das wohl

Wasserfall."

Agile Teams brauchen nicht dokumentieren!

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 …

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?

entier

Inhalt

Was ist nochmal Architektur?

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?

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?

entier

Prozess Werkzeugkette

entier

Struktur?Werkzeuge?

Medien?

Doku-Format?Grafiken?

Ziel-gruppen?

entier

Struktur?Werkzeuge?

Medien?

Ziel-gruppen?

arc42 Templates

entier

Struktur?Werkzeuge?

Medien?

Ziel-gruppen?

Video, Podcast

Präsentation

Blog/Wiki

Dokument

PDFHTML

E-ReaderPapier

entier

Struktur?Werkzeuge?

Medien?

Ziel-gruppen?

Zielgruppen identifizieren

Projektleiter

Produkt-

manager

TesterBetrieb

experten

Entwickler

Architekt

Braucht jeder alles?

• Inhalte pro Zielgruppe festlegen

• möglichst ein zentrales Dokument

• (automatisiert) verschiedene Ausgabedokumente generieren

entier

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

EntwicklerWorkflow

Alternative Datenformate

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

AsciiDoc

Markup generieren

• JavaDoc/Annotations

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

• Schnittstellenbeschreibung (WSDL, Swagger, WADL)

• DB-Schema (SchemaCrawler)

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

entier

Struktur?Werkzeuge?

Medien?

Ziel-gruppen?

… und Enterprise Architect, Magic Draw, …

yEd ist ein kostenloses

Visualisierungsprogramm

Quelle für Bilder/Grafiken

• UML-Modelle

• Bildverarbeitung/Visualisierungsprogramme

• Textuelle Beschreibung (ASCII-Art)

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

image::bild.png[Alternativtext]

Quellen:

Sourcecode

DB-Schema

XML-Modell

Muss nicht aktuell gehalten werden!

Generation Plain-Text Diagramme

entier

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

Szenario 1: User-Feedback

"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

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

Szenario 4: Schnittstellenbeschreibung

• Generierung aus WSDL, WADL, Swagger

• Einbindung in Build-Prozess

• Swagger2Markup

• JAX-RS Analyzer

• Spring REST Docs

Szenario 5: Ausführbare Dokumentation

• Quellcode-Struktur in Graph-Datenbank importieren

• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten

entier

Struktur?Werkzeuge?

Medien?

Ziel-gruppen?

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

info@oio.de

?Fragen ?

Weinheimer Str. 68

68309 Mannheim

www.oio.de

info@oio.de

Vielen Dank für Ihre

Aufmerksamkeit !

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

Documents

Lernziele - 2 komplett.pdf · Math 5. Klasse Dossier 2 Sachaufgaben / Proportionalität Lernziele Proportionalität Daten ablesen Grafiken lesen Diagramme ablesen Diagramme zeichnen

Diagramme und Graphen erstellen - Apache OpenOffice · PDF fileEinführung Einführung Diagramme und Graphen können leistungsfähige Hilfsmittel sein, um dem Leser In-formationen

Objektorientierte Konzepte Dynamische Konzepte: Zustandsautomat UML-Diagramme: Zustandsdiagramm Aktivitätsdiagramm

Diagramme - unileoben.ac.at...Excel 2019 Dagmar Serb V.01 1 DIAGRAMME ... 1.1 Diagramm erstellen - Blitzvariante 1. Markieren Sie den gewünschten Datenbereich (Im gezeigten Beispiel

Diagramme lesen Einleitung. Diagramme lesen Schalter

Der Innovations-Inkubator Lüneburg für Studierende ... · PDF fileggfls. Bildunterschrift für Grafiken, Foto, Diagramme ggfls. Bildunterschrift für Grafiken, Foto, Diagramme ggfls

Excel - Diagramme - LUIS · PDF fileMicrosoft Excel – Diagramme Seite 2 Handbücher Excel 2010 – Fortgeschrittene Techniken und Excel 2016 – Fortgeschrittene Techniken als E-Book

Diagramme, Statistiken - btmdx1.mat.uni-bayreuth.de · Diagramme, Statistiken 1. Audi-Bilanz Am Ende eines jeden Jahres erstellen Firmen eine Bilanz der Unternehmensergebnis-se, um

Voronoi Diagramme und deren Nutzen im 3D Druck · PDF fileVoronoi Diagramme und deren Nutzen im 3D-Druck ROBIN SCHENDERLEIN HAMBURG, 01.06.2016

Selbstbericht an den Senat der Martin-Luther-Universität ... · Ausfüllenden zu, da sie rein deskriptiv erfolgte. Die folgenden Diagramme beruhen Die folgenden Diagramme beruhen

TRENDS & TECHNOLOGIE MESSTECHNIK€¦ · parente und übersichtliche Präsentation der Daten. Als Darstellungselemente ste-hen Digitalanzeigen, Balkendiagramme, y-t-Diagramme, x-y-Diagramme,

MITTEILUNGEN - library.foi.hr · der Indikator-Diagramme von dem der theoretischen. Auf Tafel III wurden die theoretischen Diagramme für die Maschinen Typ Habsburg entwickelt und

Tutorat IV: Diagramme, Datenkontrolle, Wahrscheinlichkeitsrechnung 19.11.2009 christina.dorn0@googlemail.com

Mathematik-Dossier Mengen, Zahlen, Diagramme · RepetitionsdossierMengen A.Räz / 19.09.07 Seite 1 Mathematik-Dossier Mengen, Zahlen, Diagramme Inhalt: • Mengendarstellung im Venn-

Diagramme und Graphen erstellen¼hrung Einführung Diagramme und Graphen können leistungsfähige Hilfsmittel sein, um dem Leser In-formationen zu verdeutlichen. OpenOffice.org Calc

Karnaugh - Diagramme - SuS · Karnaugh (-Veitch) - Diagramme (KMAPs) bezeichnet werden § Sie geben einen grafischen Eindruck der Funktion und können zur Logikminimierung benutzt

THAILAND IMPORT-EXPORT 2014 ลำาดับความสำาคัญ … · thailand import-export 2014 76,467.1 ล้านบาท = มูลค่าการขาดดุล

SOFTWARE ENGINEERING 11 - joller-voss.ch€¦ · In UML wurden die Aktivitäten Diagramme als Subset der Zustandsdiagramme definiert. Gemäss UML sind Aktivitäten Diagramme Zustandsdiagramme,

Import Export Novemberplan

Diagramme - bildungsserver.berlin-brandenburg.de · Referenzaufgaben Diagramme LISUM / SenBWF 2013 ProLesen-Transfer Berlin Modul „Sachtexte lesen und verstehen“ 1 A Ich kann