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

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 9

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 11

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

Tools zur Konvertierung Geringste Einstiegshürde: Gradle und asciidoctorj Maven ist aufwändiger, gut unterstützt Gradle bezüglich weiterer Build-Steps flexibler

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

Diagramme: PlantUML 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 22

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

treat Docs-as-Code IV: automate 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 31

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

.docx bzw. MS Word

Slide 33

Slide 33 text

...bzw. pdf

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 37

Slide 36

Slide 36 text

Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 38

Slide 37

Slide 37 text

Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 39

Slide 38

Slide 38 text

Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 40

Slide 39

Slide 39 text

Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 41

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

Bonus: Export PPT

Slide 46

Slide 46 text

docToolchain 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 48

Slide 47

Slide 47 text

Fragen? Antworten! 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 49 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