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

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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 2

Dr. Gernot Starke innoq Fellow Softwarearchitektur Entwurf Evolution + Modernisierung Dokumentation Reviews

Was machen wir die nächsten 50 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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 4

Das VENOM Projekt VEry NOrMal System Gewachsene Dokumentation Unterschiedliche Stakholder Aufgrund verschiedener Änderungen stets im Wandel Hoher Pflegeaufwand 20.02.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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 6

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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 7

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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 8

Demo eine erste Konvertierung 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] 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 9

Demo eine erste Konvertierung demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3" } 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 10

Demo eine erste Konvertierung 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> 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 11

Demo eine erste Konvertierung build.gradle demo.adoc console output http://asciidoctor.org/docs/render-documents/ 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 12

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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 14

doch die Reise beginnt erst Geoff ist mit seiner Entscheidung erst mal zufrieden die alte Dokumentation muss aber zunächst überführt werden.docx.adoc.adoc.html.adoc Geoff entscheidet sich im Rahmen einer Überarbeitung die Dokumentation per Copy & Paste in AsciiDoc zu überführen. 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 16

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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 17

treat Docs-as-Code I: Version Control.adoc.adoc.adoc.html 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 18

treat Docs-as-Code II: Git-Flow Fork PR.adoc.adoc.adoc.adoc.html 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 19

treat Docs-as-Code III: Build-Server Fork PR On Change Build- Server Publish.adoc.adoc.adoc.adoc.html 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 20

Diagramme Geoff stört sich weiterhin an dem hohen Pflegeaufwand für Diagramme Beherrscht AsciiDoc nicht PlantUML? 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 21

Diagramme: PlantUML 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 22

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 venom private -right-> venom groups --> venom corporate --> venom gov -up-> venom bodies -up-> venom ops --> venom internal -left-> venom ---- 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 23

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! 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 24

Diagramme Im Zweifel Pfeile immer vom Aufrufenden zum Aufgerufenen Noch keinen eigenen Stil gefunden? => C4 von Simon Brown ist ein guter Start http://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 26

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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 27

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. 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 28

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. 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 29

treat Docs-as-Code IV: automate === 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[] === 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 30

treat Docs-as-Code IV: automate 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 31

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

.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á 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 36

Zusammenarbeit 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 37

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! 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 42

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 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 43

Automatisiertes Testing der Doku https://github.com/aim42/htmlsanitycheck 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 44

demnächst: Linting http://www.hemingwayapp.com/ https://github.com/btford/write-good 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 45

Bonus: Export PPT Sprechernotizen enthalten asciidoc Slides und asciidoc werden automatisch exportiert

Bonus: Export PPT

doctoolchain 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 48

Fragen? Antworten! https://doctoolchain.github.io https://doctoolchain.github.io/doctoolchain https://jaxenter.de/tag/hhgdc https://docs-as-co.de https://arc42.org Ralf.D.Mueller@gmail.com @RalfDMüller https://rdmueller.github.io @doctoolchain @doctoolchain Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com 20.02.2018 @RalfDMueller @arc42tipps @doctoolchain 49