Page 1
arc42, AsciiDoc, Gradle & Co. Im Einsatz
DB Systel GmbH | Ralf D. Müller | JavaLand | Brühl | 19.03.2019
Platzhalter für Titelbild – Hier können Sie Bilder aus der Mediathek einfügen!Placeholder for title picture – You can insert here pictures from the Mediathek!
Docs-as-Code
Page 2
DB Systel GmbH | Ralf D. Müller | 19.03.20192
Page 3
Incomplete or confusing documentation#1 Problem with Open Source
DB Systel GmbH | Ralf D. Müller | 19.03.20193
Page 4
Ralf D. Müller
Software Architect @ DB Systel mit Schwerpunkt
Web-Technologien
Qualität (Security, Testautomation)
Produktivität (Gradle, Groovy, Grails)
Prozessoptimierung
In der Freizeit Geek, arc42 Contributor &Maintainer von docToolchain
DB Systel GmbH | Ralf D. Müller | 19.03.20195
Page 5
Dr. Gernot Starke – innoQ Fellow
Softwarearchitektur
Entwurf
Evolution + Modernisierung
Dokumentation
Reviews
+49 177 [email protected]
DB Systel GmbH | Ralf D. Müller | 19.03.20196
Page 6
Was machen wir die nächsten 40 Minuten?
Mischung aus Tipps zu arc42 und docs-as-codeBest Practice zum Umgang zur Pflege einer
ArchitekturdokumentationExperimentelle Features :-)Vorschläge aus Erfahrung, keine Silver Bullet
DB Systel GmbH | Ralf D. Müller | 19.03.20197
Page 7
Was ist Docs-as-Code?
DB Systel GmbH | Ralf D. Müller |19. März 20198
,--._______,-.
,',' , . ,_`-.
/ / ,' , _` ``. | ) `-..
(,';'""`/ '"`-._ ` \/ ______ \\
: ,o.-`- ,o. )\` -' `---.))
: , d8b ^-. '| `. ` `.
|/ __:_ `. | , ` ` \
| ( ,-.`-. ;' ; ` : ;
| | , `. / ; : \
;-'`:::._,`.__),' : ;
/ , `- `-- ; |
/ \ ` , |
( ` : : ,\ |
\ `. : : : ,' \ :
\ `|-- ` \ ,' ,-' :-.-';
: |`--.______; | : :
: / | | | \
| ; ; ; / ;
_/--' | -hrr- :`-- / \_:_:_|
,',',' | |___ \
`^._,--' / , , .)
`-._,-'
------------------------------------------------
This ASCII pic can be found at
https://asciiart.website/index.php?art=animals/dogs
Page 8
VEry NOrMal System
Gewachsene Dokumentation
Unterschiedliche Stakholder
Aufgrund verschiedener Änderungen stets im Wandel
Hoher Pflegeaufwand
Das VENOM Projekt
DB Systel GmbH | Ralf D. Müller | 19.03.20199
Page 9
Darf ich vorstellen? Geoff – Solution Architect
Geoff ist Solution Architect bei SAMM Inc
Zuständig für VENOM
Starker technischer Background
Aufgaben:
Weiterentwicklung der Architektur
Pflege der Dokumentation
Kommunikation der Architektur
DB Systel GmbH | Ralf D. Müller | 19.03.201910
Page 10
DB Systel GmbH | Ralf D. Müller | 19.03.201911
Page 11
arc42
DB Systel GmbH | Ralf D. Müller | 19.03.201912
Page 12
Heutiger Fokus: Architektur Docs-as-Code
Wie schreibe ich eine System-Dokumentation?
Dr. Peter Hruschkahttp://www.peterhruschka.eu/
Dr. Gernot Starkehttp://gernotstarke.de/
http://arc42.org/
DAS Template für die Dokumentation eines Software Systems.
DB Systel GmbH | Ralf D. Müller | 19.03.201913
Page 13
arc42 …
… ist das Standard-Template im deutschsprachigen Raum
… ist verfügbar in Deutsch, Englisch und Spanisch und Russisch
… ist verfügbar in > 9 Formaten (.adoc, .docx, .rst, .md, .tex …)
… gibt der Dokumentation eine einheitliche Struktur
… ist verfügbar mit und ohne Hilfestellung
… hilft die richtigen Aspekte richtig zu dokumentieren
DB Systel GmbH | Ralf D. Müller | 19.03.201914
Page 14
arc42 – ein Kleiderschrank für Dokumentation
DB Systel GmbH | Ralf D. Müller | 19.03.201915
Page 15
arc42 – ein Kleiderschrank für Dokumentation
1. Requirements & Goals
2. Constraints
3. Scope & Context
4. Solution Strategy
5. Building Block View
6. Runtime View
7. Deployment View
10. Quality Scenarios
11. Risks & Tech Debt
12. Glossary
9. Decisions
8. Crosscutting Concepts
DB Systel GmbH | Ralf D. Müller | 19.03.201916
Page 16
Format der Dokumentation
MS Word ist der etablierte Standard
Arc42 existiert in vielen Formaten:
Docx latex htmlAsciidoc textile confluencemarkdown
Geoff wählt AsciiDoc aufgrund vieler Vorteile AsciiDoc
DB Systel GmbH | Ralf D. Müller | 19.03.201917
Page 17
arc42 als AsciiDoc Template
== Architecture Constraints
[role="arc42help"]
****
.Contents
Any requirement that constrains software architects in their freedom of design and
implementation decisions or decision about the development process. These constraints
sometimes go beyond individual systems and are valid for whole organizations and
companies.
.Motivation
Architects should know exactly where they are free in their design decisions and where
they must adhere to constraints.
Constraints must always be dealt with; they may be negotiable, though.
.Form
Simple tables of constraints with explanations.
If needed you can subdivide them into
technical constraints, organizational and political constraints and
conventions (e.g. programming or versioning guidelines, documentation or naming
conventions)
****
DB Systel GmbH | Ralf D. Müller | 19.03.201918
Page 18
arc42 Formate
DB Systel GmbH | Ralf D. Müller | 19.03.201919
AsciiDoc ist aus unserer Sicht das flexibelste Format
Da es in alle anderen Formate (fast verlustfrei) gewandelt werden kann, gibt es immer „Plan B“
Page 19
Treat Docs-as-Code
DB Systel GmbH | Ralf D. Müller | 19.03.201920
Page 20
demo.adoc build.gradle console output
= A first Headline
And a first paragraph.It continous on the next headline
Second paragraph.
== Second-Level Headline
A link to http://asciidoctor.org/docs[Asciidoctor.org]
Demo – eine erste Konvertierung
DB Systel GmbH | Ralf D. Müller | 19.03.201921
Page 21
demo.adoc build.gradle console output
plugins { id "org.asciidoctor.convert" version "1.5.3" }
Demo – eine erste Konvertierung
DB Systel GmbH | Ralf D. Müller | 19.03.201922
Page 22
build.gradle demo.adoc console output
PS C:\Users\Demo\jax2017\demo1> gradle asciidoc:asciidoctorio/console not supported; tty will not be manipulated
BUILD SUCCESSFUL
Total time: 4.554 secsPS C:\Users\Demo\jax2017\demo1>
Demo – eine erste Konvertierung
DB Systel GmbH | Ralf D. Müller | 19.03.201923
Page 23
build.gradle demo.adoc console output
Demo – eine erste Konvertierung
http://asciidoctor.org/docs/render-documents/
DB Systel GmbH | Ralf D. Müller | 19.03.201924
Page 24
Tools zur Konvertierung
DB Systel GmbH | Ralf D. Müller | 19.03.201925
Geringste Einstiegshürde: Gradle und asciidoctorj
Maven ist aufwändiger, gut unterstützt
Gradle bezüglich weiterer Build-Steps flexibler
Page 25
Out-of-the-Box Features
„ablenkungsfrei“ – Dokumentation wie eMails schreiben
Gliederung in Unterdokumente
Neugliederung je nach Stakeholder
Bilder werden referenziert, nicht eingebettet
leichte Versionierung „handle Docs-as-Code“
Formatierung von Source-Code
Reviews, Pull-Requests, Versionierung durch Git
Konvertierung nach HTML5 und DocBook
DB Systel GmbH | Ralf D. Müller | 19.03.201926
Page 26
.adoc.adoc
…doch die Reise beginnt erst
Geoff ist mit seiner Entscheidung erst mal zufrieden
die alte Dokumentation muss aber zunächst überführt werden
Geoff entscheidet sich im Rahmen einer Überarbeitung die Dokumentation per Copy & Paste in AsciiDoc zu überführen.
.docx .adoc .html
DB Systel GmbH | Ralf D. Müller | 19.03.201928
Page 27
treat Docs-as-Code
Geoff erkennt, dass die Transformation nach AsciiDoc erst der Anfang war
Als nächstes möchte er durch den Docs-as-Code Ansatz die Überarbeitung der Dokumentation weiter vereinfachen
DB Systel GmbH | Ralf D. Müller | 19.03.201929
Page 28
treat Docs-as-Code I: Version Control
.adoc.adoc.adoc .html
DB Systel GmbH | Ralf D. Müller | 19.03.201930
Page 29
treat Docs-as-Code II: Git-Flow
.adoc.adoc.adoc .html
Fork
PR
.adoc
DB Systel GmbH | Ralf D. Müller | 19.03.201931
Page 30
treat Docs-as-Code III: Build-Server
.adoc.adoc.adoc .html
Fork
PR
.adoc
Build-Server
On Change
Publish
DB Systel GmbH | Ralf D. Müller | 19.03.201932
Page 31
The End?
DB Systel GmbH | Ralf D. Müller | 19.03.201933
Danke für Ihre Aufmerksamkeit!
Fragen?
Page 32
Diagramme
DB Systel GmbH | Ralf D. Müller | 19.03.201934
Page 33
Diagramme
http://plantuml.com/
http://asciidoctor.org/docs/asciidoctor-diagram/
Komplexe Diagramme als einfachen Text verwalten
DB Systel GmbH | Ralf D. Müller | 19.03.201935
Page 34
PlantUML
DB Systel GmbH | Ralf D. Müller | 19.03.201936
Page 35
Diagramme: PlantUML
.Benutzer und Benutzergruppen von VENOM[plantuml]----!pragma graphviz_dot jdot
(VENOM\ni.B.O.S.S) as venom"Private User" -right-> venom"User Groups" --> venom"Corporate Users" --> venom"Government Users" -up-> venom"Regulation &\nStandard Bodies" -up-> venom"Operations" --> venom"Internal Users" -left-> venom----
DB Systel GmbH | Ralf D. Müller | 19.03.201937
Page 36
Diagramme: PlantUML
DB Systel GmbH | Ralf D. Müller | 19.03.201938
Page 37
Diagramme: PlantUML
DB Systel GmbH | Ralf D. Müller | 19.03.201939
Page 38
draw.io
DB Systel GmbH | Ralf D. Müller |19. März 201940
PNG-Diagramm
<xml>…
</xml>Meta-Daten
Page 39
draw.io
DB Systel GmbH | Ralf D. Müller |19. März 201941
Page 40
Diagramme: Nicht malen, modellieren!
DB Systel GmbH | Ralf D. Müller | 19.03.201943
Page 41
treat Docs-as-Code IV: automate
Betreiber und Administratoren von VENOM
Flexibilität hinsichtlich Betriebsumgebung, Betriebssystem. Möglichst wenig Aufwand bei technischer Administration und Inbetriebnahmen. Technisches Monitoring.
DB Systel GmbH | Ralf D. Müller | 19.03.201945
Page 42
treat Docs-as-Code IV: automate
{adoc:stakeholder}| Operations| Betreiber und Administratoren von VENOM| Flexibilität hinsichtlich Betriebsumgebung, Betriebssystem. Möglichst wenig Aufwand bei technischer Administration und Inbetriebnahmen. Technisches Monitoring.
DB Systel GmbH | Ralf D. Müller | 19.03.201946
Page 43
=== Stakeholder
==== Users and Groups of Users
[[figure-users]]image::ea/1.5_Stakeholder.png[title="Users and Groups of Users"]
[cols="2,3,3,2" options="header"].Users and Groups of Users|===| Role | Description | Goal | Comment
include::../../ea/stakeholder.ad[]
|===
treat Docs-as-Code: automate!
DB Systel GmbH | Ralf D. Müller | 19.03.201947
Page 44
treat Docs-as-Code IV: automate
DB Systel GmbH | Ralf D. Müller | 19.03.201948
Page 45
Don‘t know how to draw your component diagrams?
=> take a look at the C4-Model by Simon Brown
https://c4model.com/
Context, Containers, Components, Classes
Diagramme
DB Systel GmbH | Ralf D. Müller | 19.03.201949
Page 46
Stakeholder
DB Systel GmbH | Ralf D. Müller | 19.03.201950
Page 47
Stakeholder
Geoff bemerkt schnell, dass nicht jeder mit einer online HTML-Dokumentation glücklich ist
Er muss für unterschiedliche Stakeholder die Dokumente auch unterschiedlich aufbereiten
DB Systel GmbH | Ralf D. Müller | 19.03.201951
Page 48
.docx bzw. MS Word
http://pandoc.org
DB Systel GmbH | Ralf D. Müller | 19.03.201952
Page 49
.docx bzw. MS Word
DB Systel GmbH | Ralf D. Müller | 19.03.201953
Page 50
...bzw. pdf
DB Systel GmbH | Ralf D. Müller | 19.03.201954
Page 51
Modulare Dokumentation
DB Systel GmbH | Ralf D. Müller |19. März 201955
arc42-master.adoc
kapitel1.adoc
kapitel2.adocpublic class HelloWorld {
public static void main (String[] args) {
// Ausgabe Hello World!
System.out.println("Hello World!");
}
}
include
include
include
kapitel8.adoc
kapitel8.1.adoc
include
business-master.adoc
security-master.adoc
Page 52
Seitenumbrüche
DB Systel GmbH | Ralf D. Müller | 19.03.201956
… machen bei single-page HTML keinen Sinn
… sind aber klasse für PDF und .docx!
<<<<
Apropos single-page HTML…
:data-uri:
Page 53
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201957
Page 54
Zusammenarbeit
Aber alle anderen Dokumente sind in Confluence…
Confluence speichert die Seiten intern als xhtml
…und hat eine REST-API
et voilá…
DB Systel GmbH | Ralf D. Müller | 19.03.201958
Page 55
Zusammenarbeit: Confluence
DB Systel GmbH | Ralf D. Müller | 19.03.201959
Page 56
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201960
Page 57
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201961
Page 58
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201962
Page 59
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201963
Page 60
Besser: statische Seiten
DB Systel GmbH | Ralf D. Müller |19. März 201964
Page 61
Besser: statische Seiten
DB Systel GmbH | Ralf D. Müller |19. März 201965
Page 62
Besser: statische Seiten -
DB Systel GmbH | Ralf D. Müller |19. März 201966
Page 63
Besser: statische Seiten -
DB Systel GmbH | Ralf D. Müller |19. März 201967
Page 64
Zusammenarbeit - Tabellen
DB Systel GmbH | Ralf D. Müller |19. März 201968
Page 65
Tabellen in AsciiDoc
[options="header",cols="7,23,17,33,11,11"]
|===
| Nr.
| Name
| Rolle
| Email
| Telefon
| PLZ
| 1
| Hubert Kleinschmidt
| Product Owner
| [email protected]
| 555 102
| 40388
| 2
| Erika Mustermann
| Scrum Master
| [email protected]
| 555 103
| 41222
|===
mit MS Excel!
DB Systel GmbH | Ralf D. Müller | 19.03.201969
Page 66
Managing Tables in AsciiDoc
DB Systel GmbH | Ralf D. Müller | 19.03.201970
Page 67
Export PPT
Sprechernotizen enthalten asciidoc
Slides und asciidoc werden automatischexportiert
DB Systel GmbH | Ralf D. Müller | 19.03.201971
Page 68
Export PPT
DB Systel GmbH | Ralf D. Müller | 19.03.201972
Page 69
Testing
DB Systel GmbH | Ralf D. Müller | 19.03.201973
Page 70
Broken Links
Geoff fällt auf, dass er immer wieder mit Probleme mit Tippfehlern in Dateinamen oder Verlinkungen im Dokument hat
Wie löst man solche Probleme mit Code?
=> natürlich mit automatisierten Tests!
DB Systel GmbH | Ralf D. Müller | 19.03.201974
Page 71
Automatisiertes Testing der Doku
DB Systel GmbH | Ralf D. Müller | 19.03.201975
Broken Cross References (aka Broken Internal Links)
Missing Images Files
Multiple Definitions of Bookmarks or ID’s
Missing Local Resources
Missing Alt-tags in Images
https://github.com/aim42/htmlSanityCheck
Page 72
Automatisiertes Testing der Doku
DB Systel GmbH | Ralf D. Müller | 19.03.201976
https://github.com/aim42/htmlSanityCheck
Page 73
… demnächst: Linting
http://www.hemingwayapp.com/
https://github.com/btford/write-good
DB Systel GmbH | Ralf D. Müller | 19.03.201977
Page 74
docToolchain
DB Systel GmbH | Ralf D. Müller | 19.03.201978
Page 75
DB Systel GmbH | Ralf D. Müller | 19.03.201979
Page 76
Vielen Dank für Ihre Aufmerksamkeit!
https://docs-as-co.de
@docToolchain
Image-Credits: Title - Photo by Susan Yin on Unsplash Clipart: presentermedia.com, licenced to [email protected]
www.dbsystel.de