Docs-as code: arc42, AsciiDoc, Gradle & Co. combined

Docs-as code: arc42, AsciiDoc, Gradle & Co. combined

Gr8conf-Conf session, 31. May .2018, Copenhagen, Denmark

http://2018.greachconf.com/sessions/docs-as-code-arc42-asciidoc-gradle-co-combined/

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

The combination of AsciiDoc and Gradle should be well known by now. But what if you want to go beyond? Have you ever tried to include UML diagrams the easy way, convert Excel to AsciiDoc or export your results to Confluence?
This talk shows you what you can really do if you treat your docs as code and apply some tricks you only did to your code before.
Forget about copy & paste your images to your documentation – let the build do it!
Create different docs for different stakeholders and even run automated tests on your docs!

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

May 30, 2018
Tweet

Transcript

  1. Docs-as-Code arc42, AsciiDoc, Gradle & Co. combined Ralf D. Müller

    @docToolchain
  2. Ralf D. Müller By Day Solution Architect @ Deutsche Bank

    Digital Factory In my spare time Geek: Web-Technologies Quality (Security, Testautomation) Productivity (Gradle, Groovy, Grails) arc42 contributor & docToolchain maintainer 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 2
  3. What you can expect… Pragmatic architecture documentation Tips‘n‘Tricks for arc42

    and docs-like-code Experimental Features :-) Best Practice but no Silver Bullets 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 3 5
  4. 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 4 Treat Docs-as-Code or Docs-like-Code a

    short History of Docs-as-Code
  5. 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 – Convert AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 5
  6. demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3"

    } Demo – Convert AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 6
  7. build.gradle demo.adoc console output PS C:\Users\Demo\greach2018\demo1> gradle asciidoc :asciidoctor io/console

    not supported; tty will not be manipulated BUILD SUCCESSFUL Total time: 4.554 secs PS C:\Users\Demo\greach2018\demo1> Demo – Convert AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 7
  8. build.gradle demo.adoc console output Demo – Convert AsciiDoc http://asciidoctor.org/docs/render-documents/ 31.05.2018

    @RalfDMueller @arc42Tipps @docToolchain 8
  9. Out-of-the-Box Features „distraction free“ – write docs like code or

    an email Modular docs Reference images – don‘t embedd them Integration of source code Easy reviews, pull-requests and versioning through Git Convert to HTML5, DocBook 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 9
  10. treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR

    .adoc Build- Server On Change Publish 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 10
  11. Focus for today: Architecture Docs-as-Code How to write a Solution

    Architecture? 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 11 Dr. Peter Hruscka http://www.peterhruschka.eu/ Dr. Gernot Starke http://gernotstarke.de/ http://arc42.org/ the Template for documentation of software and system architecture.
  12. arc42 … 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 12 … is the

    standard template in german speaking countries … is available in German, English and Spanish … is available in 9 formats (.adoc, .docx, .rst, .md, .tex …) … gives your docs a structure … is available with or without help … helps you to write the right content, the right way
  13. arc42 – a wardrobe for your docs 31.05.2018 @RalfDMueller @arc42Tipps

    @docToolchain 13
  14. arc42 – a wardrobe for your docs 1. Requirements &

    Goals 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 14 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
  15. arc42 as AsciiDoc Template 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 15 ==

    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) ****
  16. Diagrams30.05.2018 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 16

  17. Diagrams 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 17 http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ …let‘s you

    handle your diagrams as Text!
  18. Diagrams: 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 18
  19. Diagrams: PlantUML 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 19

  20. Diagrams: PlantUML 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 20

  21. PlantUML Not all types of diagrams are well suited for

    plantUML. But sequencediagrams are a perfect fit! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 21
  22. Diagrams: Don‘t draw – model! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 22

  23. treat Docs-as-Code: automate! Betreiber und Administratoren von VENOM Flexibilität hinsichtlich

    Betriebsumgebung, Betriebssystem. Möglichst wenig Aufwand bei technischer Administration und Inbetriebnahmen. Technisches Monitoring. 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 23
  24. treat Docs-as-Code: 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. 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 24
  25. === 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 25
  26. treat Docs-as-Code: automate! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 26

  27. Diagrams 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 27
  28. Stakeholder 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 28

  29. .docx / MS Word http://pandoc.org 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 29

  30. .docx bzw. MS Word 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 30

  31. ...or maybe pdf? 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 31

  32. Page Breaks … don‘t make sense for single-page HTML …

    but for PDF and .docx! <<<< 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 32
  33. Collaboration 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 33

  34. Working Together „… but all other docs are in Confluence“

    Confluence stores pages as xhtml… …and provides a REST-API! et voilá… 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 34
  35. Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 35

  36. Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 36

  37. Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 37

  38. Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 38

  39. Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 39

  40. Managing Tables in AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 40 [options="header",cols="7,23,17,33,11,11"]

    |=== | Nr. | Name | Rolle | Email | Telefon | PLZ | 1 | Hubert Kleinschmidt | Product Owner | h.kleinschmidt@example.com | 555 102 | 40388 | 2 | Erika Mustermann | Scrum Master | e.mustermann@example.com | 555 103 | 41222 |=== with MS Excel
  41. Managing Tables in AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 41

  42. Testing 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 42

  43. Automated Tests for your 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 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 43
  44. Automated Tests for your Docs https://github.com/aim42/htmlSanityCheck 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain

    44
  45. … coming soon: Linting 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 45 http://www.hemingwayapp.com/

    https://github.com/btford/write-good
  46. Bonus: Export PPT Speakernotes contain AsciiDoc Automatic export of slides

    and AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 46
  47. Bonus: Export PPT 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 47

  48. docToolchain 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 48

  49. 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 49 Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com

    Questions?
  50. 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 50 Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com

    Thanx for your Attention!