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

Vortrag vom 21.02.2018 auf dem Entwicklertag Frankfurt

https://entwicklertag.de/frankfurt/2018/docs-code-arc42-asciidoc-gradle-co-im-einsatz

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
https://twitter.com/RalfDMueller
https://twitter.com/docToolchain

Der Vortrag zeigt, wie Sie die Qualität Ihrer Dokumentation erhöhen und gleichzeitig den Aufwand zur Pflege reduzieren, indem Sie Ihre Dokumentation genauso wie Ihren Code verwalten und in den Build integrieren.

Anhand des Beispiels einer Architekturdokumentation, zeigt Ralf wie Sie mit dem arc42-Template im AsciiDoc-Format und Gradle als Build-Tool einfach Diagramme in Ihre Dokumentation integrieren, Stakeholderspezifische Dokumente erzeugen und verschiedene Ausgabeformate generieren.

Reviewfähige PDF-Dokumente? Publishing nach Confluence? Integration einer Präsentation? Alles kein Problem! Einige Teile der Doku können Sie sogar automatisiert testen.

Zwischendurch bekommen Sie zahlreiche Tipps, wie und wo Sie systematisch den Aufwand für Dokumentation reduzieren können und trotzdem lesbare, verständliche und praxistaugliche Ergebnisse produzieren.

Transcript

1. Docs-as-Code Docs-as-Code: arc42, AsciiDoc, Gradle & Co. im Einsatz Ralf D. Müller @docToolchain
2. 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
3. Dr. Gernot Starke innoQ Fellow Softwarearchitektur ▪ Entwurf ▪ Evolution + Modernisierung ▪ Dokumentation ▪ Reviews
4. 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
5. 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
6. 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
7. 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
8. 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
9. 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
10. 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
11. 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
12. build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/ 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 12
13. Tools zur Konvertierung Geringste Einstiegshürde: Gradle und asciidoctorj Maven ist aufwändiger, gut unterstützt Gradle bezüglich weiterer Build-Steps flexibler
14. 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
15. .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
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
17. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 18
18. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR .adoc 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 19
19. 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
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
21. Diagramme: PlantUML 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 22
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
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
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
25. 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
26. 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
27. 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
28. === 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
29. treat Docs-as-Code IV: automate 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 31
30. 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
31. .docx bzw. MS Word http://pandoc.org
32. .docx bzw. MS Word
33. ...bzw. pdf
34. 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
35. Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 37
36. Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 38
37. Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 39
38. Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 40
39. Zusammenarbeit 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 41
40. 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
41. 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
42. Automatisiertes Testing der Doku https://github.com/aim42/htmlSanityCheck 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 44
43. … demnächst: Linting 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 45 http://www.hemingwayapp.com/ https://github.com/btford/write-good
44. Bonus: Export PPT ▪Sprechernotizen enthalten asciidoc ▪Slides und asciidoc werden automatisch exportiert
45. Bonus: Export PPT
46. docToolchain 20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 48
47. 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