softwarearchitektur kontinuierlich und effizient dokumentieren · 2021. 1. 19. · 2...
TRANSCRIPT
-
1
Orientation in Objects GmbH
Weinheimer Str. 6868309 Mannheim
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.
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 6
Anforderungenklären
Architekturentwerfen
Architekturbewerten
aus: Effektive Softwarearchitekturen (G. Starke)
Architekturkommunizieren
War
um
dok
um
entier
en?
-
4
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 8
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
-
5
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 9
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 10
Hauptsache, du machst es
nicht mit Word!
http://www.machsmit.de/kampagne/motive_der_kampagne/index.php
-
6
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 11
Foto von Antranias: https://pixabay.com/en/telescope-view-distant-binoculars-1201497/ (CC0 Public Domain Lizenz)
Textverarbeitung
Visio
Powerpoint
UML-Tools
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
AsciiDoc
14
-
8
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
Welcher Markup-Typ bin ich?
15
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 16
Templates für:
Microsoft Word
Confluence
Markdown, AsciiDoc
Latex, DocBook
HTML, EPUB
Textile
-
9
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 17
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 18
Foto von UliSchu: https://pixabay.com/en/organization-register-folder-files-1205171/ (CC0 Public Domain Lizenz)
-
10
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 19
• 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)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 20
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 21
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 22
Single Sourceof Truth
IncludesQuellcode verlinkenPlatzhalter einbetten
Foto von pcdazero: https://pixabay.com/en/umbrellas-sea-holiday-summer-beach-921501/ (CC0 Public Domain Lizenz)
-
12
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 23
Inhaltegenerieren
WSDL, SwaggerDB-SchemaAnnotationenJavaDocMarkup generieren
Foto von ClassicallyPrinted: https://pixabay.com/en/wind-turbine-energy-electricity-937715/ (CC0 Public Domain Lizenz)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 24
Schnittstellenbeschreibung generieren
-
13
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 25
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 26
Ein Bild sagt mehr als tausend Worte!Ein Bild sagt mehr als tausend Worte!
-
14
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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]
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 28
Tools
… und Visio, Enterprise Architect, Magic Draw, …
yEd ist ein kostenloses Visualisierungsprogramm
-
15
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
Diagramme als textuelle Beschreibung
29
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 30
"AsciiArt"
-
16
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 31
Online-Tools
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 32
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 35
Agile Projekte
iterativkontinuierlich
Foto von Unsplash: https://pixabay.com/de/fluss-bachlauf-bach-l%C3%A4ndlich-768654/ (CC0 Public Domain Lizenz)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 36
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 37
HTML,
PDF, …
Leser
EntwicklerDokumentation als
Plain Text
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
Ausrichtung auf Zielgruppen und Ausgabeformate
38
-
20
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
Video, Podcast
Präsentation
Blog/Wiki
Dokument
PDFHTML
E-ReaderPapier
Single Sourceof Truth
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 40
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
-
21
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 41
https://twitter.com/ewolff/status/1024292485869326336
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 42
Wenn man die Architektur
nicht erklären/dokumentieren
kann, ist sie zu kompliziert!
-
22
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 43
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)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 44
Validierung
SanityChecksBroken LinksPDFUnit
Foto von skeeze: https://pixabay.com/en/military-honor-guard-inspection-642639/ (CC0 Public Domain Lizenz)
-
23
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 45
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)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 46
-
24
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 47
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 48
-
25
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 49
Living Documentation
+
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 50
[[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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 51
Softwarearchitekturvisualisierung coden
https://structurizr.com/
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 52
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
-
27
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 53
KlassischeArchitekten
Rolle
Foto von scottwebb: https://pixabay.com/en/toronto-architecture-skyscraper-1594940/ (CC0 Public Domain Lizenz)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 54
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 55
Dokumentation braucht einen
Kümmerer
VorbereitenPlanenErinnernDelegierenIntegrierenPrüfen
Foto von Berzin: https://pixabay.com/en/ambulance-doctor-students-game-2166079/ (CC0 Public Domain Lizenz)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 56
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
-
29
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 58
Continuous
Documentation
Documentation
as Code
REPO
-
30
Orientation in Objects GmbH
Weinheimer Str. 6868309 Mannheim
Vielen Dank für Ihre Aufmerksamkeit!
59
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 60
Verschiedene SzenarienFoto von nikidinov: https://pixabay.com/en/ballet-swan-lake-ballerina-dance-2124652/ (CC0 Public Domain Lizenz)
-
31
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
Szenario 2: AsciiDoctor, Maven, PlantUML
• Erstellen AsciiDoc und PlantUML in IDE mit Preview
• Maven-Plugin zum Erzeugen des HTML/PDF
62
-
32
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
Szenario 4: Schnittstellenbeschreibung
• Generierung aus WSDL, WADL, Swagger
• Einbindung in Build-Prozess
• Swagger2Markup
• JAX-RS Analyzer
• Spring REST Docs
64
-
33
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
Szenario 5: Ausführbare Dokumentation
• Quellcode-Struktur in Graph-Datenbank importieren
• Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten
65
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH
Szenario 7: Wiki
67
CC BY-SA 3.0, https://de.wikipedia.org/wiki/Ward_Cunningham#/media/File:Ward_Cunningham_-_Commons-1.jpg
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 68
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
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 69
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)
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 70
TasksMentions
Kommentare Jira
-
36
Softwarearchitektur kontinuierlich und effizient do kumentieren© Orientation in Objects GmbH 71
Balsamiq Mockups
Gliffy (Diagramme, UML)