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 [email protected] 

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 | [email protected] | 555 102 | 40388 | 2 | Erika Mustermann | Scrum Master | [email protected] | 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 [email protected] @docToolchain [email protected] @RalfDMüller https://rdmueller.github.io @docToolchain