Softwarearchitektur Kontinuierlich Und Effizient Dokumentieren

Home , PlantUML, YEd

Softwarearchitektur kontinuierlich und effizient dokumentieren

Orientation in Objects GmbH

Weinheimer Str. 68 68309 Mannheim

www.oio.de 1 Version: 1.0 [email protected]

Ihre Sprecher

Falk Sippach (@sippsack)

Trainer, Berater, Entwickler

Architektur Co-Organisator Agile Softwareentwicklung Codequalität

Commiter DukeCon

1 Zusammenschluss Trivadis und OIO

Im Mai diesen Jahres haben sich Trivadis und Orientation in Objects (OIO) zusammen- geschlossen. Gemeinsam stärken und erweitern wir unser Angebot im Bereich Java und agiler Softwareentwicklung.

Gemeinsam bieten wir ein Neu finden Sie im Trivadis zwölfmonatiges Trainee- Trainingsangebot auch Kurse, Programm an, das Experten die von der OIO entwickelt und für Java- und Web- durchgeführt werden. technologien ausbildet.

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.

2 Doku-Smells Die7 Sünden der Architekturdokumentationdokumentation

Foto von jesperbkskov: https://pixabay.com/en/fish-newspaper-food-russian-salted-224097/ (CC0 Public Domain Lizenz )

Anforderungen klären

Architektur Architektur bewerten entwerfen

Architektur kommunizieren

Warum dokumentieren? Warum aus: Effektive Softwarearchitekturen (G. Starke)

3 Gründe für eine Architektur-Dokumentation

Entwurfsunterstützung

Kommunikation

Bewertbarkeit

Frage nach Warum

Neue Mitarbeiter

Grafik von The Practical Dev: https://github.com/thepracticaldev/orly-full-res/blob/master/notwritingdocs-big.png (CC0 Public Domain Lizenz )

WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

4 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

Hauptsache, du machst es nicht mit Word!

http://www.machsmit.de/kampagne/motive_der_kampagne/index.php

5 Textverarbeitung Visio Powerpoint UML-Tools

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

Alternative Datenformate zu Textverarbeitung

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

kollaborativ eingeschränkte Lesbarkeit

Wikis LaTex/DocBook visuell, kurz & knapp Austauschformat Mindmaps Richtext

6 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

7 Welcher Markup-Typ bin ich?

Templates für:

Microsoft Word Confluence Markdown, AsciiDoc Latex, DocBook HTML, EPUB Textile

8 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

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

9 Unser täglich Entwickler-Brot:

• Plain-Text • Entwicklungs- umgebung • Kommandozeilen- werkzeuge • Versions- verwaltung

Foto von geralt: https://pixabay.com/de/unternehmer-start-start-up-karriere-696976/ (CC0 Public Domain Lizenz )

Code-Nähe Ablage im Repo Versionier-/diffbar Synchrone Auslieferung Offlinefähig Teil des Build-Prozess Generierung Automatisierung Flexible Ausgabeformate

Documentation as Code

Foto von ahobbit: https://pixabay.com/en/vault-business-bank-vault-bank-1144249/ (CC0 Public Domain Lizenz )

10 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

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 )

11 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

12 WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

Ein Bild sagt mehr als tausend Worte!

13 Quelle für Bilder/Grafiken im Binärformat

• Export aus UML-Modellen • Manuelle Erstellung (Bildverarbeitung/Visualisierungsprogramme)

• Einbetten/Verlinken in Markup-Sprachen:

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

Tools

yEd ist ein kostenloses Visualisierungsprogramm

… und Visio, Enterprise Architect, Magic Draw, …

14 Diagramme als textuelle Beschreibung

"AsciiArt"

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

16 Quellcode DB-Schema PlantUML + @startuml interface DemoService UML-Modell AsciiDoc DemoService <|-- DemoServiceImpl

Schnittstellen generieren enum State { NEW Konfiguration OPEN APPROVED # Werte von State IN_PROGRESS FIXED * NEW interface DemoService { } * OPEN String foobar(); * APPROVED } @enduml * IN_PROGRESS * FIXED class DemoServiceImpl implements DemoService { @Override public String foobar() { return "demo"; } } enum State { NEW , OPEN , APPROVED , IN_PROGRESS , FIXED }

WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

17 Agile Projekte

iterativ kontinuierlich

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

Automatisiert erstellen Regelmässig ausliefern Ständig ergänzen Reviewen Nachbessern

Continuous Documentation

Foto von Ted Van Pelt: https://www.flickr.com/photos/bantam10/5209157298 (CC BY 2.0 Lizenz )

18 HTML, PDF, …

Entwickler Dokumentation als Plain Text Leser

Ausrichtung auf Zielgruppen und Ausgabeformate

19 Single Source of Truth

Blog/Wiki

Präsentation Dokument

PDF Video, Podcast HTML E-Reader Papier

WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

20 https://twitter.com/ewolff/status/1024292485869326336

Wenn man die Architektur nicht erklären/dokumentieren kann, ist sie zu kompliziert!

21 nur so viel wie nötig geringe Änderungsrate Zielgruppenbedürfnisse Feedback einpflegen

Pragmatik/Effektivität

Foto von PublicDomainPictures: https://pixabay.com/de/ansager-audio-schwarz-kassette-316584/ (CC0 Public Domain Lizenz )

Foto von Devanath: https://pixabay.com/de/bleistift-b%C3%BCro-design-kreative-1209544/ (CC0 Public Domain Lizenz )

Validierung

SanityChecks Broken Links PDFUnit

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

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

23 Kontinuierliche Analyse der Architekturkonformität

Quellcode Report Artefakte

Regeln (Soll-Architektur) Veröffentlichung (SonarQube)

https://www.msg.group/news/open-source-einsatz-zur-qualitaetssicherung-in-der-software-entwicklung

24 Living Documentation

[[architecture:UndefinedDependencies]] [source,cypher,role=constraint,requiresConcepts=" architecture:DefinedDependencies PlantUML There must not be dependencies between Maven project which have not been defined. ---- AsciiDoc MATCH (p1:Maven:Project)-[:CREATES]->(:Artifact)-[:CONTAINS] (p2:Maven:Project)-[:CREATES]->(:Artifact)-[:CONTAINS] (t2)-[:DEPENDS_ON]->(t1) WHERE NOT (p1)-[:DEFINES_DEPENDENCY]->(p2) RETURN * ---- [[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 Dependency impl -> spi : Defines Dependency spi -> api : Defines Dependency ----

25 Softwarearchitekturvisualisierung coden

https://structurizr.com/

WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

26 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 Moderator

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

27 Vorbereiten Planen Erinnern Delegieren Integrieren Prüfen

Dokumentation braucht einen Kümmerer

Foto von Berzin: https://pixabay.com/en/ambulance-doctor-students-game-2166079/ (CC0 Public Domain Lizenz )

WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE Smells

- HANDARBEIT TOTE DOKU

Doku ELFENBEINTURM

28 WYSIWYG Plain Text ABLAGE Documentation as Code REDUNDANZEN Generierung TEXTWÜSTE Mehr Grafiken HANDARBEIT Automatisierung TOTE DOKU Lebendige Dokument.

Zusammenfassung ELFENBEINTURM Kümmerer

REPO

Continuous Documentation Documentation as Code

29 Vielen Dank für Ihre Aufmerksamkeit!

Orientation in Objects GmbH

Weinheimer Str. 68 68309 Mannheim

www.oio.de [email protected] 59

Verschiedene Szenarien

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

30 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 2: AsciiDoctor, Maven, PlantUML

• Erstellen AsciiDoc und PlantUML in IDE mit Preview

• Maven-Plugin zum Erzeugen des HTML/PDF

31 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

32 Szenario 5: Ausführbare Dokumentation

• Quellcode-Struktur in Graph-Datenbank importieren

• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten

Szenario 6: docToolchain

https://github.com/docToolchain/docToolchain

docToolchain is an implementation of the docs-as-code approach for software architecture. The basis of docToolchain is the philosophy that software documentation should be treated in the same way as code together with the arc42 template for software architecture.

33 Szenario 7: Wiki

CC BY-SA 3.0, https://de.wikipedia.org/wiki/Ward_Cunningham#/media/File:Ward_Cunningham_-_Commons-1.jpg

Zusammenarbeit

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

Foto von makamuki0: https://pixabay.com/de/castellers-castells-h%C3%A4nde-ananas-921018/ (CC0 Public Domain Lizenz )

34 Strukturiert? Plain-Text? Offlinefähigkeit? Versionierung? Code-Nähe? Automatisierung? Druckausgabe? Zielgruppen? Kontextwechsel

Schlund des Wiki

Foto von MartinStr: https://pixabay.com/de/krokodil-thailand-z%C3%A4hne-f%C3%BCtterung-225615/ (CC0 Public Domain Lizenz )

Tasks Mentions

Kommentare Jira

35 Gliffy (Diagramme, UML)

Balsamiq Mockups