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
DB Systel GmbH | Ralf D. Müller | 19.03.20192
Incomplete or confusing documentation#1 Problem with Open Source
DB Systel GmbH | Ralf D. Müller | 19.03.20193
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
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
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
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
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
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
DB Systel GmbH | Ralf D. Müller | 19.03.201911
arc42
DB Systel GmbH | Ralf D. Müller | 19.03.201912
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
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
arc42 – ein Kleiderschrank für Dokumentation
DB Systel GmbH | Ralf D. Müller | 19.03.201915
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
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
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
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“
Treat Docs-as-Code
DB Systel GmbH | Ralf D. Müller | 19.03.201920
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
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
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
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
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
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
.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
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
treat Docs-as-Code I: Version Control
.adoc.adoc.adoc .html
DB Systel GmbH | Ralf D. Müller | 19.03.201930
treat Docs-as-Code II: Git-Flow
.adoc.adoc.adoc .html
Fork
PR
.adoc
DB Systel GmbH | Ralf D. Müller | 19.03.201931
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
The End?
DB Systel GmbH | Ralf D. Müller | 19.03.201933
Danke für Ihre Aufmerksamkeit!
Fragen?
Diagramme
DB Systel GmbH | Ralf D. Müller | 19.03.201934
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
PlantUML
DB Systel GmbH | Ralf D. Müller | 19.03.201936
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
Diagramme: PlantUML
DB Systel GmbH | Ralf D. Müller | 19.03.201938
Diagramme: PlantUML
DB Systel GmbH | Ralf D. Müller | 19.03.201939
draw.io
DB Systel GmbH | Ralf D. Müller |19. März 201940
PNG-Diagramm
<xml>…
</xml>Meta-Daten
draw.io
DB Systel GmbH | Ralf D. Müller |19. März 201941
Diagramme: Nicht malen, modellieren!
DB Systel GmbH | Ralf D. Müller | 19.03.201943
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
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
=== 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
treat Docs-as-Code IV: automate
DB Systel GmbH | Ralf D. Müller | 19.03.201948
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
Stakeholder
DB Systel GmbH | Ralf D. Müller | 19.03.201950
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
.docx bzw. MS Word
http://pandoc.org
DB Systel GmbH | Ralf D. Müller | 19.03.201952
.docx bzw. MS Word
DB Systel GmbH | Ralf D. Müller | 19.03.201953
...bzw. pdf
DB Systel GmbH | Ralf D. Müller | 19.03.201954
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
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:
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201957
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
Zusammenarbeit: Confluence
DB Systel GmbH | Ralf D. Müller | 19.03.201959
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201960
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201961
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201962
Zusammenarbeit
DB Systel GmbH | Ralf D. Müller | 19.03.201963
Besser: statische Seiten
DB Systel GmbH | Ralf D. Müller |19. März 201964
Besser: statische Seiten
DB Systel GmbH | Ralf D. Müller |19. März 201965
Besser: statische Seiten -
DB Systel GmbH | Ralf D. Müller |19. März 201966
Besser: statische Seiten -
DB Systel GmbH | Ralf D. Müller |19. März 201967
Zusammenarbeit - Tabellen
DB Systel GmbH | Ralf D. Müller |19. März 201968
Tabellen in AsciiDoc
[options="header",cols="7,23,17,33,11,11"]
|===
| Nr.
| Name
| Rolle
| Telefon
| PLZ
| 1
| Hubert Kleinschmidt
| Product Owner
| 555 102
| 40388
| 2
| Erika Mustermann
| Scrum Master
| 555 103
| 41222
|===
mit MS Excel!
DB Systel GmbH | Ralf D. Müller | 19.03.201969
Managing Tables in AsciiDoc
DB Systel GmbH | Ralf D. Müller | 19.03.201970
Export PPT
Sprechernotizen enthalten asciidoc
Slides und asciidoc werden automatischexportiert
DB Systel GmbH | Ralf D. Müller | 19.03.201971
Export PPT
DB Systel GmbH | Ralf D. Müller | 19.03.201972
Testing
DB Systel GmbH | Ralf D. Müller | 19.03.201973
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
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
Automatisiertes Testing der Doku
DB Systel GmbH | Ralf D. Müller | 19.03.201976
https://github.com/aim42/htmlSanityCheck
… demnächst: Linting
http://www.hemingwayapp.com/
https://github.com/btford/write-good
DB Systel GmbH | Ralf D. Müller | 19.03.201977
docToolchain
DB Systel GmbH | Ralf D. Müller | 19.03.201978
DB Systel GmbH | Ralf D. Müller | 19.03.201979
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