Lebendige Architektur- Dokumentation - kontinuierlich und ......• UML-Diagramme mit PlantUML,...

Orientation in Objects GmbH

Weinheimer Str. 68

68309 Mannheim

www.oio.de

info@oio.deVersion:

Lebendige Architektur-

Dokumentation -

kontinuierlich und effizient

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

Ihr Sprecher

Architektur

Agile Softwareentwicklung

Codequalität

Trainer, Berater, Entwickler

Falk Sippach (@sippsack)

Co-Organisator

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

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

entier

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

entier

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

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

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 …

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?

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

geringe Änderungsrate

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

Single Sourceof Truth

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 (Single Source of Truth)

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

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

AsciiDoc

Welcher Markup-Typ bin ich?

Tools für Markup-Sprachen

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

Markup generieren

• aus JavaDoc/Annotations

• aus Enumwerten (Zustandsübergänge)

• Schnittstellenbeschreibung (WSDL, Swagger, WADL)

• DB-Schema (SchemaCrawler)

entier

Struktur?Werkzeuge?

Medien?

Ziel-gruppen?

Quelle für Bilder/Grafiken

• Export aus UML-Modellen

• Manuelle Erstellung (Bildverarbeitung/Visualisierungsprogramme)

• Einbetten/Verlinken in Markup:

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

image::bild.png[Alternativtext]

… und Visio, Enterprise Architect, Magic Draw, …

yEd ist ein kostenloses

Visualisierungsprogramm

Diagramme als textuelle Beschreibung

• viele Formate (PlantUML, ditaa, …)

• Einbetten in Markup-Dokumente:

"AsciiArt"

Online-

Generation Plain-Text Diagramme

Nie mehr aktuell halten müssen!

Quellen:

Sourcecode

DB-Schema

XML-Modell

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

info@oio.de

?Fragen ?

Weinheimer Str. 68

68309 Mannheim

www.oio.de

info@oio.de

Vielen Dank für Ihre

Aufmerksamkeit !

Lebendige Architektur- Dokumentation - kontinuierlich und ......• UML-Diagramme mit PlantUML,...

Documents

Transcript of Lebendige Architektur- Dokumentation - kontinuierlich und ......• UML-Diagramme mit PlantUML,...

Diagramme de constellation

DIAGRAMME DE PERT

UML-Diagramme XPlanGML Version 4.0 - xplanungwiki.de · UML-Diagramme XPlanGML Version 4.0.2 Datum: 3. November 2011 Autor: Dr. J. Benner, KIT

Diagramme de Classes (1)

[SMC3] Cours Diagramme de Phase

Implémentation de VLAN 802.1q sur Cisco ICS 7750 avec la ... · Diagramme du réseau Ce document utilise la configuration réseau indiquée dans le diagramme suivant : Dans ce diagramme,

Diagramme de classes - Base - Exercicesresinfo.free.fr/BTSIRIS/Cours/Programmation/UML/UML Concept de … · UML : Diagramme de classes Diagramme de classes - Base - Exercices.doc

DATEV Export mit SAP Business One Version 9 · PUBLIC Solution Management SAP Business One September, 2018 DATEV Export mit SAP Business One Version 9.3

DIAGRAMME DE PHASES ET PROPRIETES ...

Diagramme in MS Office - oerttel.net · 2019. 1. 2. · Abbildung 2.1: Auswahl des Datenbearbeitungs-Modus und Wertetabelle in PowerPoint oder Word 2.1 Arbeiten mit der Wertetabelle

Diplomarbeit: Editor für Entity Relationship Diagramme mit …eclipse-erd.sourceforge.net/DA.pdf · 2005-10-27 · This Entity Relationship Diagram Editor runs under Eclipse. It

Transformation du diagramme de classe en modèle relationnel

Interaction magma-sédiment et impact environnemental … · (c) diagramme de Harker appliqué aux roches sédimentaires p.23 Figure 12 : Diagramme de l’évolution des compositions

Construction dun diagramme de flux dinformations

PHY144 - Diagramme des forces (DCL) · 3 Dessinez le diagramme des forces (DCL) du bateau (directement sur le schéma) : M. Clisson et C. Alinot 3. PHY144 ENCADREMENT - Diagramme

Construction du diagramme de MOLLIER Lecture du graphe Lecture du graphe Construction du diagramme Construction du diagramme.

Diagramme Ichikawa

UML - Diagramme de cas d'utilisation (Use case diagram) · UML - Diagramme de cas d’utilisation (Use case diagram) IlhemBoussaïd ilhem_boussaid@yahoo.fr Université des Sciences

Rapport Diagramme de Classe

Les modèles dans UP - home.mis.u-picardie.frfurst/docs/3-UML_ConceptionEtSuite.pdf · Diagramme d'état Un diagramme d'état permet de décrire sous forme d'un automate déterministe