Docs-as-Code Docs-as-Code: arc42, AsciiDoc, Gradle & Co. im Einsatz Ralf D. Müller @docToolchain

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 (Security, Testautomation) Produktivität (Gradle, Groovy, Grails) Maintainer von docToolchain 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 2

Dr. Gernot Starke innoQ Fellow Softwarearchitektur ▪ Entwurf ▪ Evolution + Modernisierung ▪ Dokumentation ▪ Reviews +49 177 7282570 gernot.starke@innoq.com

Was machen wir die nächsten 60 Minuten? Mischung aus Tipps zu arc42 und docs-like-code Best Practice zum Umgang zur Pflege einer Architekturdokumentation Experimentelle Features :-) Vorschläge aus Erfahrung, keine Silver Bullet 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 4

Das VENOM Projekt VEry NOrMal System Gewachsene Dokumentation Unterschiedliche Stakholder Aufgrund verschiedener Änderungen stets im Wandel Hoher Pflegeaufwand 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 5

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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 6

30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 7

arc42 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 8

Heutiger Fokus: Architektur Docs-as-Code Wie schreibe ich eine System-Dokumentation? 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 9 Dr. Peter Hruscka http://www.peterhruschka.eu/ Dr. Gernot Starke http://gernotstarke.de/ http://arc42.org/ DAS Template für die Dokumentation eines Software Systems.

arc42 … 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 10 … ist das Standard-Template im deutschsprachigen Raum … ist verfügbar in Deutsch, Englisch und Spanisch … 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 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 11

arc42 – ein Kleiderschrank für Dokumentation 1. Requirements & Goals 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 12 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 html Asciidoc textile confluence markdown Geoff wählt AsciiDoc aufgrund vieler Vorteile 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 13

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“ 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 14

Treat Docs-as-Code 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 15

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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 16

demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3" } Demo – eine erste Konvertierung 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 17

build.gradle demo.adoc console output PS C:\Users\Demo\jax2017\demo1> gradle asciidoc :asciidoctor io/console not supported; tty will not be manipulated BUILD SUCCESSFUL Total time: 4.554 secs PS C:\Users\Demo\jax2017\demo1> Demo – eine erste Konvertierung 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 18

build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/ 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 19

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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 21

arc42 als AsciiDoc Template 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 23 == 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) ****

.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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 24

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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 25

treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 26

treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR .adoc 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 27

treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR .adoc Build- Server On Change Publish 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 28

Diagramme 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 29

Diagramme 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 30 http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ Komplexe Diagramme als einfachen Text verwalten

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 ---- 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 31

Diagramme: PlantUML 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 32

Diagramme: PlantUML 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 33

PlantUML Nicht alle Diagramm-Typen sind geeignet für PlantUML Sequenzdiagramme sind jedoch perfekt! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 34

Asciidoctor Plugins AsciidoctorJ oder jRuby? Verschiedene Output-Formate beachten! 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 35

Diagramme: Nicht malen, modellieren! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 36

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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 37

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. 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 38

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. 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 39

=== 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! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 40

treat Docs-as-Code IV: automate 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 41

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 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 42 Diagramme

Stakeholder 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 43

.docx bzw. MS Word http://pandoc.org

.docx bzw. MS Word

...bzw. pdf

Seitenumbrüche … machen bei single-page HTML keinen Sinn … sind aber klasse für PDF und .docx! <<<< Apropos single-page HTML… :data-uri: 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 48

Zusammenarbeit 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 49

Zusammenarbeit Aber alle anderen Dokumente sind in Confluence… Confluence speichert die Seiten intern als xhtml …und hat eine REST-API et voilá… 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 50

Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 51

Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 52

Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 53

Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 54

Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 55

Tabellen in AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 56 [options="header",cols="7,23,17,33,11,11"] |=== | Nr. | Name | Rolle | Email | Telefon | PLZ | 1 | Hubert Kleinschmidt | Product Owner | h.kleinschmidt@example.com | 555 102 | 40388 | 2 | Erika Mustermann | Scrum Master | e.mustermann@example.com | 555 103 | 41222 |=== mit MS Excel!

Managing Tables in AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 57

Testing 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 58

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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 60

Automatisiertes Testing der Doku https://github.com/aim42/htmlSanityCheck 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 61

… demnächst: Linting 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 62 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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 65

Fragen? Antworten! 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 66 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 ralf.d.mueller@gmail.com @docToolchain Ralf.D.Mueller@gmail.com @RalfDMüller https://rdmueller.github.io @docToolchain