View
6
Download
0
Category
Preview:
Citation preview
1
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
info@oio.deVersion:
Softwarearchitektur kontinuierlich und effizient dokumentieren
11.0
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH
Ihre Sprecher
2
Trainer, Berater, Entwickler
Falk Sippach (@sippsack)
Architektur
Agile 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 Trivadis
Trainingsangebot auch Kurse,
die von der OIO entwickelt und
durchgeführt werden.
Softwarearchitektur kontinuierlich und effizient dokumentieren© 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 dokumentieren© Orientation in Objects GmbH 5
Die 7 Sünden der
Architekturdokumentation
Doku-Smells
Foto von jesperbkskov: https://pixabay.com/en/fish-newspaper-food-russian-salted-224097/ (CC0 Public Domain Lizenz)
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 6
Anforderungen
klären
Architektur
entwerfen
Architektur
bewerten
aus: Effektive Softwarearchitekturen (G. Starke)
Architektur
kommunizieren
War
um
dok
um
entier
en?
4
Softwarearchitektur kontinuierlich und effizient dokumentieren© 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 dokumentieren© Orientation in Objects GmbH 8
Dok
u-Sm
ells
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
5
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 9
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
Softwarearchitektur kontinuierlich und effizient dokumentieren© 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 dokumentieren© 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 dokumentieren© 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 & knappAustauschformat
7
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH
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
13
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH
AsciiDoc
14
8
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH
Welcher Markup-Typ bin ich?
15
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 16
Templates für:
Microsoft Word
Confluence
Markdown, AsciiDoc
Latex, DocBook
HTML, EPUB
Textile
9
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 17
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
Softwarearchitektur kontinuierlich und effizient dokumentieren© 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 dokumentieren© 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 dokumentieren© Orientation in Objects GmbH 20
Documentation as Code
Code-Nähe
Ablage im Repo
Versionier-/diffbar
Synchrone Auslieferung
Offlinefähig
Teil des Build-Prozess
Generierung
Automatisierung
Flexible Ausgabeformate
Foto von ahobbit: https://pixabay.com/en/vault-business-bank-vault-bank-1144249/ (CC0 Public Domain Lizenz)
11
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 21
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 22
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)
12
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 23
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)
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 24
Schnittstellenbeschreibung generieren
13
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 25
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 26
Ein Bild sagt mehr als tausend Worte!
14
Softwarearchitektur kontinuierlich und effizient dokumentieren© 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 dokumentieren© Orientation in Objects GmbH 28
Tools
… und Visio, Enterprise Architect, Magic Draw, …
yEd ist ein kostenloses
Visualisierungsprogramm
15
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH
Diagramme als textuelle Beschreibung
29
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 30
"AsciiArt"
16
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 31
Online-
Tools
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 32
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)
17
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH
interface DemoService {
String foobar();
}
class DemoServiceImpl implements DemoService {
@Override
public String foobar() {
return "demo";
}
}
enum State {
NEW, OPEN, APPROVED, IN_PROGRESS, FIXED
}
33
PlantUML +AsciiDoc
generieren
QuellcodeDB-Schema
UML-ModellSchnittstellenKonfiguration
@startuml
interface DemoService
DemoService <|-- DemoServiceImpl
enum State {
NEW
OPEN
APPROVED
IN_PROGRESS
FIXED
}
@enduml
# Werte von State
* NEW
* OPEN
* APPROVED
* IN_PROGRESS
* FIXED
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 34
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
18
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 35
Agile Projekte
iterativ
kontinuierlichFoto von Unsplash: https://pixabay.com/de/fluss-bachlauf-bach-l%C3%A4ndlich-768654/ (CC0 Public Domain Lizenz)
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 36
Continuous
Documentation
Automatisiert erstellen
Regelmässig ausliefern
Ständig ergänzen
Reviewen
Nachbessern
Foto von Ted Van Pelt: https://www.flickr.com/photos/bantam10/5209157298 (CC BY 2.0 Lizenz)
19
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 37
HTML,PDF, …
Leser
Entwickler Dokumentation als
Plain Text
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH
Ausrichtung auf Zielgruppen und Ausgabeformate
38
20
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH
Video, Podcast
Präsentation
Blog/Wiki
Dokument
PDFHTML
E-ReaderPapier
Single Sourceof Truth
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 40
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
21
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 41
https://twitter.com/ewolff/status/1024292485869326336
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 42
Wenn man die Architektur
nicht erklären/dokumentieren
kann, ist sie zu kompliziert!
22
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 43
Pragmatik/Effektivität
nur so viel wie nötig
geringe Änderungsrate
Zielgruppenbedürfnisse
Feedback 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 dokumentieren© Orientation in Objects GmbH 44
Validierung
SanityChecks
Broken Links
PDFUnit
Foto von skeeze: https://pixabay.com/en/military-honor-guard-inspection-642639/ (CC0 Public Domain Lizenz)
23
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 45
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)
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 46
24
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 47
https://www.msg.group/news/open-source-einsatz-zur-qualitaetssicherung-in-der-software-entwicklung
QuellcodeArtefakte
Report
Regeln(Soll-Architektur) Veröffentlichung
(SonarQube)
Kontinuierliche Analyse der Architekturkonformität
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 48
25
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 49
Living Documentation
+
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 50
[[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
----
[[architecture:UndefinedDependencies]]
[source,cypher,role=constraint,requiresConcepts="architecture:DefinedDependencies
There 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
*
----
PlantUMLAsciiDoc
26
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 51
Softwarearchitekturvisualisierung coden
https://structurizr.com/
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 52
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
27
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 53
Klassische
Architekten
Rolle
Foto von scottwebb: https://pixabay.com/en/toronto-architecture-skyscraper-1594940/ (CC0 Public Domain Lizenz)
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 54
Architekt/Senior Developer als
Ratgeber/Mentor
und ModeratorFoto von JESHOOTS: https://pixabay.com/de/warten-termin-zeitplan-zeit-eile-410328/ (CC0 Public Domain Lizenz)
28
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 55
Dokumentation braucht einen
Kümmerer
Vorbereiten
Planen
Erinnern
Delegieren
Integrieren
Prüfen
Foto von Berzin: https://pixabay.com/en/ambulance-doctor-students-game-2166079/ (CC0 Public Domain Lizenz)
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 56
WYSIWYG
REDUNDANZEN
HANDARBEIT
ABLAGE
TOTE DOKU
ELFENBEINTURM
TEXTWÜSTE
Dok
u-Sm
ells
29
Softwarearchitektur kontinuierlich und effizient dokumentieren© 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 dokumentieren© Orientation in Objects GmbH 58
Continuous
DocumentationDocumentation
as Code
REPO
30
Orientation in Objects GmbH
Weinheimer Str. 68
68309 Mannheim
www.oio.de
info@oio.de
Vielen Dank für Ihre
Aufmerksamkeit!
59
Softwarearchitektur kontinuierlich und effizient dokumentieren© 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 dokumentieren© 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 dokumentieren© 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 dokumentieren© 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 dokumentieren© 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 dokumentieren© 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 dokumentieren© 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 dokumentieren© 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 dokumentieren© Orientation in Objects GmbH 68
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)
35
Softwarearchitektur kontinuierlich und effizient dokumentieren© 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 dokumentieren© Orientation in Objects GmbH 70
TasksMentions
Kommentare Jira
36
Softwarearchitektur kontinuierlich und effizient dokumentieren© Orientation in Objects GmbH 71
Balsamiq Mockups
Gliffy (Diagramme, UML)
Recommended