Dokumentation am (Riesen-)Beispiel · Ralf D. Müller Bei Tag Solution Architect in der Digital Factory der Deutschen Bank. In der Freizeit Geek mit Schwerpunkt Web-Technologien Qualität

Docs-as-CodeDocs-as-Code: arc42, AsciiDoc, Gradle & Co. im Einsatz

Ralf D. Müller

@docToolchain

Ralf D. Müller

Bei Tag Solution Architectin der Digital Factory der Deutschen Bank.

In der Freizeit Geek mit Schwerpunkt

Web-Technologien

Qualität (Security, Testautomation)

Produktivität (Gradle, Groovy, Grails)

Maintainer von docToolchain

20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 2

Dr. Gernot StarkeinnoQ Fellow

Softwarearchitektur ▪ Entwurf▪ Evolution + Modernisierung ▪ Dokumentation ▪ Reviews

Was machen wir die nächsten 50 Minuten?

Mischung aus Tipps zu arc42und docs-like-code

Best Practice zum Umgang zur Pflege einer Architekturdokumentation

Experimentelle Features :-)

Vorschläge aus Erfahrung, keine Silver Bullet


Das VENOM Projekt

VEry NOrMal System

Gewachsene Dokumentation

Unterschiedliche Stakholder

Aufgrund verschiedener Änderungen stets im Wandel

Hoher Pflegeaufwand


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


Format der Dokumentation

MS Word ist der etablierte Standard

Arc42 existiert in vielen Formaten:

Docx latex html

Asciidoc textile confluence

markdown

Geoff wählt AsciiDoc aufgrund vieler Vorteile


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“


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


Diagramme

Geoff stört sich weiterhin an dem hohen Pflegeaufwand für Diagramme

Beherrscht AsciiDoc nicht PlantUML?


Diagramme: PlantUML


Diagramme: PlantUML

.Benutzer und Benutzergruppen von VENOM[plantuml]----!pragma graphviz_dot jdot:Private User: as private:User Groups: as groups:Corporate Users: as corporate:Government Users: as gov:Regulation &\nStandard Bodies: as bodies:Operations: as ops:internal Users: as internal(VENOM\ni.B.O.S.S) as venomprivate -right-> venomgroups --> venomcorporate --> venomgov -up-> venombodies -up-> venomops --> venominternal -left-> venom----


Diagramme: PlantUML

http://plantuml.com/

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

Komplexe Diagramme als einfachen Text verwalten

Nicht alle Diagrammtypen sind für PlantUML gleichgut geeignet.Sequenzdiagramme sind jedoch ein sehr guter Anwendungsfall!




Diagramme

Im Zweifel Pfeile immer vom Aufrufenden zum Aufgerufenen

Noch keinen eigenen Stil gefunden?=> C4 von Simon Brown ist ein guter Starthttp://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html


http://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html

Diagramme: Modellierung

Geoff pflegt seine Architektur in einem UML-Modellierungstool

Das Einbetten der Grafiken in die Dokumentation ist jedoch schwerfällig

Des weiteren macht Geoff sich auch gerne Notizen im UML-Modell, welche dann in der Dokumentation fehlen


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

==== Benutzer und Benutzergruppen

[[figure-users]]image::ea/1.5_Stakeholder.png[title="Benutzer und Benutzergruppen von VENOM"]

[cols="2,3,3,2" options="header"].Benutzer und Benutzergruppen|===| Rolle | Beschreibung | Ziel | Bemerkungen

include::../../ea/stakeholder.ad[]

|===





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

Zusammenarbeit

Aber alle anderen Dokumente sind in Confluence…

Confluence speichert die Seiten intern als xhtml

…und hat eine REST-API

et voilá…


Zusammenarbeit


Zusammenarbeit


Zusammenarbeit


Zusammenarbeit


Zusammenarbeit


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/

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

Bonus: Export PPT

▪Sprechernotizen enthalten asciidoc

▪Slides und asciidoc werden automatisch exportiert

Bonus: Export PPT

docToolchain


Fragen? Antworten!


https://doctoolchain.github.io

https://doctoolchain.github.io/docToolchain

https://jaxenter.de/tag/hhgdc

https://docs-as-co.de

https://arc42.org

Clipart: presentermedia.com, licenced to [email protected]

@docToolchain

[email protected]

@RalfDMüller

https://rdmueller.github.io

@docToolchain

https://doctoolchain.github.io/

https://doctoolchain.github.io/docToolchain

https://jaxenter.de/tag/hhgdc

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

https://arc42.org/

https://rdmueller.github.io/

Documents

Dokumentation am (Riesen-)Beispiel · Ralf D. Müller Bei Tag Solution Architect in der Digital Factory der Deutschen Bank. In der Freizeit Geek mit Schwerpunkt Web-Technologien Qualität