Softwarearchitektur kontinuierlich und effizient dokumentieren · 2021. 1. 19. · 2 Zusammenschluss Trivadis und OIO Im Mai diesen Jahres haben sich Trivadis und Orientation in Objects

1

Orientation in Objects GmbH

Weinheimer Str. 6868309 Mannheim

[email protected]:

Softwarearchitektur kontinuierlich

und effizient dokumentieren

11.0

Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH

Ihre Sprecher

2

Trainer, Berater, Entwickler

Falk Sippach (@sippsack)

ArchitekturAgile Softwareentwicklung

CodequalitätCo-Organisator

Commiter DukeCon

2

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 zwölfmonatiges Trainee-Programm an, das Experten für Java- und Web-technologien ausbildet.

Neu finden Sie im TrivadisTrainingsangebot auch Kurse, die von der OIO entwickelt und durchgeführt werden.


Abstract

4

Man kann zwar an vielen Stellen nachlesen, wie manArchitekturdokumentation strukturiert. Aber auf der Suche nacheiner praktikablen Handhabung zur Erstellung und Pflege endendie meisten Versuche in der WYSIWYG-Hölle einerTextverarbeitung oder im tiefen Schlund eines Wikis.

In diesem Vortrag wollen wir uns anschauen, wie aufbauend aufbestehenden Tools und Textformaten eine möglichstredundanzfreie Dokumentation erstellt und für verschiedeneZielgruppen in ansprechenden Formaten ausgeliefert werdenkann. Es wird dabei um Begriffe wie Continuous Documentationund Documentation as Code gehen.

3

Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 5

Die 7 Sünden7 Sünden7 Sünden7 Sünden der

Architekturdokumentationdokumentationdokumentationdokumentation

Doku-Smells

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


Anforderungenklären

Architekturentwerfen

Architekturbewerten

aus: Effektive Softwarearchitekturen (G. Starke)

Architekturkommunizieren

War

um

dok

um

entier

en?

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

5


WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

Dok

u-Sm

ells


Hauptsache, du machst es

nicht mit Word!

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

6


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

Textverarbeitung

Visio

Powerpoint

UML-Tools


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 & knapp

Austauschformat

7


Markdown

Normaler Text wird so dargestellt wie eingegeben.

*Kursiv*, **Fett** und ***Fett kursiv*** bzw. _Kurs iv_, __Fett__ und ___Fett kursiv___

Markiert Text als `Inline-Quelltext`

Ein Code-Blockdurch Einrückungmit vier Leerzeichen

* Ein Punkt in einer ungeordneten Liste* Ein Unterpunkt, um vier Leerzeichen eingerückt

1. Ein Punkt in einer geordneten Liste2. Ein weiterer Punkt1. Noch ein Punkt bei mehrfacher Angabe derselben Z iffer

# Überschrift in Ebene 1#### Überschrift in Ebene 4

13


AsciiDoc

14

8


Welcher Markup-Typ bin ich?

15


Templates für:

Microsoft Word

Confluence

Markdown, AsciiDoc

Latex, DocBook

HTML, EPUB

Textile

9


WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

Dok

u-Sm

ells


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

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äheAblage im RepoVersionier-/diffbarSynchrone AuslieferungOfflinefähigTeil des Build-ProzessGenerierungAutomatisierungFlexible Ausgabeformate

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

11


WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

Dok

u-Sm

ells


Single Sourceof Truth

IncludesQuellcode verlinkenPlatzhalter einbetten

Foto von pcdazero: https://pixabay.com/en/umbrellas-sea-holiday-summer-beach-921501/ (CC0 Public Domain Lizenz)

12


Inhaltegenerieren

WSDL, SwaggerDB-SchemaAnnotationenJavaDocMarkup generieren

Foto von ClassicallyPrinted: https://pixabay.com/en/wind-turbine-energy-electricity-937715/ (CC0 Public Domain Lizenz)


Schnittstellenbeschreibung generieren

13


WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

Dok

u-Sm

ells


Ein Bild sagt mehr als tausend Worte!Ein Bild sagt mehr als tausend Worte!

14


Quelle für Bilder/Grafiken im Binärformat

• Export aus UML-Modellen

• Manuelle Erstellung (Bildverarbeitung/Visualisierungsprogramme)

• Einbetten/Verlinken in Markup-Sprachen:

27

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

image:: bild.png[Alternativtext]


Tools

… und Visio, Enterprise Architect, Magic Draw, …

yEd ist ein kostenloses Visualisierungsprogramm

15


Diagramme als textuelle Beschreibung

29


"AsciiArt"

16


Online-Tools


Generation Plain-Text-Diagramme

Quellen:

SourcecodeDB-SchemaXML-Modell

Foto von herbert2512: https://pixabay.com/en/steam-engine-toys-flywheel-drive-1592908/ (CC0 Public Domain Lizenz)

17


interface DemoService {String foobar();

}

class DemoServiceImpl implements DemoService {@Overridepublic String foobar() {

return "demo";}

}

enum State {NEW, OPEN, APPROVED, IN_PROGRESS, FIXED

}

33

PlantUML +

AsciiDoc

generieren

Quellcode

DB-Schema

UML-Modell

Schnittstellen

Konfiguration

@startuml

interface DemoServiceDemoService

18


Agile Projekte

iterativkontinuierlich

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


ContinuousDocumentation

Automatisiert erstellenRegelmässig ausliefernStändig ergänzenReviewenNachbessern

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

19


HTML,

PDF, …

Leser

EntwicklerDokumentation als

Plain Text


Ausrichtung auf Zielgruppen und Ausgabeformate

38

20


Video, Podcast

Präsentation

Blog/Wiki

Dokument

PDFHTML

E-ReaderPapier

Single Sourceof Truth


WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

Dok

u-Sm

ells

21


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


Wenn man die Architektur

nicht erklären/dokumentieren

kann, ist sie zu kompliziert!

22


Pragmatik/Effektivität

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


Validierung

SanityChecksBroken LinksPDFUnit

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

23


Ausführbare Dokumentation

Ausführbare TestsEinbettung 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)


24


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

Quellcode

Artefakte

Report

Regeln

(Soll-Architektur) Veröffentlichung

(SonarQube)

Kontinuierliche Analyse der Architekturkonformität


25


Living Documentation

+


[[architecture:DefinedDependencies][plantuml,role=concept]----[artifactId:xo.impl] as impl [artifactId:xo.api] as api [artifactId:xo.spi] as spi

impl -> api : Defines Dependencyimpl -> spi : Defines Dependencyspi -> api : Defines Dependency----

[[architecture:UndefinedDependencies]][source,cypher,role=constraint,requiresConcepts="architecture:DefinedDependenciesThere must not be dependencies between Maven project which have not been defined.----MATCH(p1:Maven:Project)-[:CREATES]->(:Artifact)-[:CONTAINS](p2:Maven:Project)-[:CREATES]->(:Artifact)-[:CONTAINS](t2)-[:DEPENDS_ON]->(t1)

WHERE NOT(p1)-[:DEFINES_DEPENDENCY]->(p2)

RETURN*

----

PlantUML

AsciiDoc

26


Softwarearchitekturvisualisierung coden

https://structurizr.com/


WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

Dok

u-Sm

ells

27


KlassischeArchitekten

Rolle

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


Architekt/Senior Developer als

Ratgeber/Mentorund Moderator

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

28


Dokumentation braucht einen

Kümmerer

VorbereitenPlanenErinnernDelegierenIntegrierenPrüfen

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


WYSIWYG

REDUNDANZEN

HANDARBEIT

ABLAGE

TOTE DOKU

ELFENBEINTURM

TEXTWÜSTE

Dok

u-Sm

ells

29


Zusa

mm

enfa

ssung

57

WYSIWYG Plain Text

REDUNDANZEN Generierung

HANDARBEIT Automatisierung

ABLAGE Documentation as Code

TOTE DOKU Lebendige Dokument.

ELFENBEINTURM Kümmerer

TEXTWÜSTE Mehr Grafiken


Continuous

Documentation

Documentation

as Code

REPO

30

Orientation in Objects GmbH

Weinheimer Str. 6868309 Mannheim

[email protected]

Vielen Dank für Ihre Aufmerksamkeit!

59


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

31


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

61


Szenario 2: AsciiDoctor, Maven, PlantUML

• Erstellen AsciiDoc und PlantUML in IDE mit Preview

• Maven-Plugin zum Erzeugen des HTML/PDF

62

32


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

63


Szenario 4: Schnittstellenbeschreibung

• Generierung aus WSDL, WADL, Swagger

• Einbindung in Build-Prozess

• Swagger2Markup

• JAX-RS Analyzer

• Spring REST Docs

64

33


Szenario 5: Ausführbare Dokumentation

• Quellcode-Struktur in Graph-Datenbank importieren

• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten

65


Szenario 6: docToolchain

66

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.

https://github.com/docToolchain/docToolchain

34


Szenario 7: Wiki

67

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


Zusammenarbeit

VerlinkungReview-/Redaktions-ProzessProzess-UnterstützungAbbildung WorkflowErweiterung über PluginsAlles in einer Box!

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

35


Schlund des Wiki

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

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


TasksMentions

Kommentare Jira

36


Balsamiq Mockups

Gliffy (Diagramme, UML)

Documents

Softwarearchitektur kontinuierlich und effizient dokumentieren · 2021. 1. 19. · 2 Zusammenschluss Trivadis und OIO Im Mai diesen Jahres haben sich Trivadis und Orientation in Objects