THHG to Painless Docs

topics: arc42, AsciiDoc, AsciiDoctor, docToolchain and Docs-as-Code

Transcript

1. The Hitchhiker‘s Guide to painless Documentation arc42, AsciiDoc und Co. in Aktion Dr. Gernot Starke & Ralf D. Müller
2. Dr. Gernot Starke innoQ Fellow Softwarearchitecture ▪ Design ▪ Evolution ▪ Documentation ▪ Reviews +49 177 7282570 gernot.starke@innoq.com
3. Ralf D. Müller By Day Solution Architect @Deutschen Bank Digital Factory In my spare time Geek: ▪ Web-Technologies ▪ Quality (Security, Testautomation) ▪ Produktivity (Gradle, Groovy, Grails…) Arc42 committer and docToolchain maintainer
4. What you can expect ▪ pragmatic Architectur Documentation ▪ Tips‘n‘Tricks for arc42 und docs-like-code ▪ Experimental Features :-) ▪ Best Practice NSB (No Silver Bullet)
5. VENOM as Example Projekt ▪ VEry NOrMal System ▪ Documentation grown over time ▪ different Stakeholders ▪ due to various updated, always changing ▪ high maintenance overhead
6. May I introduce you? Geoff – Solution Architect ▪Solution Architect for VENOM ▪solid technical background Tasks (amongst other): ▪ Manage the Evolution of the System ▪ Documentation + Communication of the Architecture
7. Documentation format •MS Word: established standard •arc42 available in many formats: • docx • asciidoc • markdown • latex • html • textile • confluence
8. arc42 Formats ▪ AsciiDoc is the most flexible (IMHO) ▪ can be transformed to all other formats with (nearly) no loss of quality -> allways a fallback plan (but you will not need it!)
9. build.gradle demo.adoc console output plugins { id "org.asciidoctor.convert" version "1.5.3" } Demo – first use of AsciiDoc
10. build.gradle demo.adoc console output = A first Headline And a first paragraph. It continuous on the next headline Second paragraph. == Second-Level Headline A link to http://asciidoctor.org/docs[Asciidoctor.org] Demo – first use of AsciiDoc
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 – first use of AsciiDoc
12. build.gradle demo.adoc console output Demo – first use of AsciiDoc http://asciidoctor.org/docs/render-documents/
13. AsciiDoc Rendering Tools ▪ easiest to use: Gradle und asciidoctorj ▪Maven more complex to use but with good support ▪Gradle is more flexible in regards to further build steps
14. Out-of-the-Box: docs-as-code • „distraction free“ write Docs like code or an email • modular • reference Images – don‘t embedd them • integration of Source-Code • Reviews, Pull-Requests, Versionierung with Git • convert to HTML5, DocBook etc.
15. referenced Sub-Documents ▪partial Includes include::subdocument.adoc[tags=xyz] ▪fix Heading levels include::subdocument.adoc[tags=xyz, leveloffset=+1]
16. .adoc .adoc …but the journey is only about to begin… ▪ Geoff is already quite satified with the results ▪ but he has to transform his old docs... .docx .adoc .html
17. treat Docs-as-Code ▪ Geoff recognizes that the transformation to AsciiDoc was only the first step ▪ next he will use the Docs-as-Code approach to further reduce the maintenance overhead
18. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html
19. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR .adoc
20. treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR .adoc Build- Server On Change Publish
21. Diagrams ▪ Geoff is annoyed by the maintenance overhead for his diagrams • Doesn‘t AsciiDoc support PlantUML?
22. Diagrams: PlantUML
23. Diagrams: 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 ----
24. Diagrams als Plain-Text: PlantUML • http://plantuml.com/ • http://asciidoctor.org/docs/asciidoctor-diagram/ Not all types of diagrams are easy to handle with PlantUML. But sequenzdiagrams are a great fit!
25. Diagrams ▪Don‘t know how to model you diagrams? => C4 by Simon Brown is a good start! http://www.codingthearchitecture.com/2014/08 /24/c4_model_poster.html
26. Diagrams: don‘t draw – modell! ▪ Geoff uses a UML-modelling tool ▪ hard to keep images up to date ▪ notes taken within UML-Modell are lost
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.
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.
29. === 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
30. treat Docs-as-Code IV: automate
31. Stakeholders ▪Geoff notices soon that not everybody likes the docs as HTML ▪He needs to create different formats and document structures for different stakeholders
32. .docx aka MS Word http://pandoc.org
33. .docx aka MS Word
34. ...or maybe pdf?
35. Docs-Review with PDF ▪… is better than with Word!
36. Page Breaks ▪ …don‘t make sense for single-page HTML ▪ …but for PDF and .docx! ▪ <<<<
37. Confluence ▪ …but all other docs are in Confluence! ▪ Confluence stores pages as xhtml… ▪ …and provides a REST-API! ▪ et voilá…
38. Teamwork
39. Teamwork
40. Teamwork
41. Teamwork
42. Teamwork
43. Broken Links ▪ ...often a problem with referenced files and hyperlinks ▪ Solution: automated Tests!
44. Automated Testing of created Docs ▪ 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
45. Automated Testing of created Docs https://github.com/aim42/htmlSanityCheck
46. Bonus: Export PPT ▪ Speaker Notes contain AsciiDoc ▪ Slides and AsciiDoc are exported through a script
47. Bonus: Export PPT
48. docToolchain
49. Thanx for your attention! Ralf D. Müller @RalfDMüller https://rdmueller.github.io @docToolchain Gernot Starke @GernotStarke http://arc42.org/ @arc42Tipps Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com