Platzhalter für Titelbild Hier können Sie Bilder aus der ... 2019 (19.03...Ralf D. Müller Software Architect @ DB Systel mit Schwerpunkt Web-Technologien Qualität (Security, Testautomation)

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


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


Dr. Gernot Starke – innoQ Fellow

Softwarearchitektur

Entwurf

Evolution + Modernisierung

Dokumentation

Reviews

+49 177 [email protected]


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


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


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



arc42


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.


http://www.peterhruschka.eu/

http://arc42.org/

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


arc42 – ein Kleiderschrank für Dokumentation


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


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


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)

****


arc42 Formate


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


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


demo.adoc build.gradle console output

plugins { id "org.asciidoctor.convert" version "1.5.3" }



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>



build.gradle demo.adoc console output


http://asciidoctor.org/docs/render-documents/


http://asciidoctor.org/docs/render-documents/

Tools zur Konvertierung


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


.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


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


treat Docs-as-Code I: Version Control

.adoc.adoc.adoc .html


treat Docs-as-Code II: Git-Flow


Fork

PR

.adoc


treat Docs-as-Code III: Build-Server


Fork

PR

.adoc

Build-Server

On Change

Publish


The End?


Danke für Ihre Aufmerksamkeit!

Fragen?

Diagramme


Diagramme

http://plantuml.com/

http://asciidoctor.org/docs/asciidoctor-diagram/

Komplexe Diagramme als einfachen Text verwalten


PlantUML


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


Diagramme: PlantUML


Diagramme: PlantUML


draw.io


PNG-Diagramm

<xml>…

</xml>Meta-Daten

draw.io


Diagramme: Nicht malen, modellieren!


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.



{adoc:stakeholder}| Operations| Betreiber und Administratoren von VENOM| Flexibilität hinsichtlich Betriebsumgebung, Betriebssystem. Möglichst wenig Aufwand bei technischer Administration und Inbetriebnahmen. Technisches Monitoring.


=== 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!




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


https://c4model.com/

Stakeholder


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


.docx bzw. MS Word

http://pandoc.org


http://pandoc.org/

.docx bzw. MS Word


...bzw. pdf


Modulare Dokumentation


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


… machen bei single-page HTML keinen Sinn

… sind aber klasse für PDF und .docx!

<<<<

Apropos single-page HTML…

:data-uri:

Zusammenarbeit


Zusammenarbeit

Aber alle anderen Dokumente sind in Confluence…

Confluence speichert die Seiten intern als xhtml

…und hat eine REST-API

et voilá…


Zusammenarbeit: Confluence


Zusammenarbeit


Zusammenarbeit


Zusammenarbeit


Zusammenarbeit


Besser: statische Seiten


Besser: statische Seiten


Besser: statische Seiten -


Besser: statische Seiten -


Zusammenarbeit - Tabellen


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!


Managing Tables in AsciiDoc


Export PPT

Sprechernotizen enthalten asciidoc

Slides und asciidoc werden automatischexportiert


Export PPT


Testing


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!


Automatisiertes Testing der Doku


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




… demnächst: Linting

http://www.hemingwayapp.com/

https://github.com/btford/write-good


http://www.hemingwayapp.com/

docToolchain



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

https://docs-as-co.de/

https://unsplash.com/photos/2JIvboGLeho?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText

https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText

Documents

Platzhalter für Titelbild Hier können Sie Bilder aus der ... 2019 (19.03...Ralf D. Müller Software Architect @ DB Systel mit Schwerpunkt Web-Technologien Qualität (Security, Testautomation)