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

Greach-Conf session, 17. May .2018, Madird, Spain

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!

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 17.03.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 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 3 5
4. 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 4 Treat Docs-as-Code or Docs-like-Code a short History of Docs-as-Code
5. Format Options 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 5 Markdown, textile, gdoc reStructuredText AsciiDoc(tor)
6. 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 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 6
7. demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3" } Demo – Convert AsciiDoc 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 7
8. 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 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 8
9. build.gradle demo.adoc console output Demo – Convert AsciiDoc http://asciidoctor.org/docs/render-documents/ 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 9
10. 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 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 10
11. treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR .adoc Build- Server On Change Publish 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 11
12. Focus for today: Architecture Docs-as-Code How to write a Solution Architecture? 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 12 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.
13. arc42 … 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 13 … 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
14. arc42 – a wardrobe for your docs 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 14
15. arc42 – a wardrobe for your docs 1. Requirements & Goals 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 15 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
16. arc42 as AsciiDoc Template 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 16 == 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) ****
17. Diagrams Architecture Docs need Diagrams Isn‘t there a PlantUML Plugin for AsciiDoctor? 17.03.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 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 18
19. Diagrams: PlantUML 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 19
20. PlantUML Not all types of diagrams are well suited for plantUML. But sequencediagrams are a perfect fit! 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 20
21. 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 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 21
22. Diagrams: don‘t draw – model! Use a UML-modelling tool for more complex diagrams! Problems: It‘s hard to keep images up to date Notes taken within the UML-model are lost 17.03.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. 17.03.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. 17.03.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! 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 25
26. treat Docs-as-Code: automate! 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 26
27. Stakeholder Not everybody likes docs rendered as HTML You need to create different formats and document structures for different stakeholders 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 27
28. .docx / MS Word http://pandoc.org 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 28
29. .docx bzw. MS Word 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 29
30. ...or maybe pdf? 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 30
31. Page Breaks … don‘t make sense for single-page HTML … but for PDF and .docx! <<<< 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 31
32. Managing Tables in AsciiDoc 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 32 [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
33. Managing Tables in AsciiDoc 17.03.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á… 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 34
35. Working Together 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 35
36. Working Together 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 36
37. Working Together 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 37
38. Working Together 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 38
39. Working Together 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 39
40. Broken Links With complex documents, you‘ll soon run into problems with referenced files and hyperlinks :-| How would you solve such a problem in your code? 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 40
41. 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 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 41
42. Automated Tests for your Docs https://github.com/aim42/htmlSanityCheck 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 42
43. … coming soon: Linting 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 43 http://www.hemingwayapp.com/ https://github.com/btford/write-good
44. Bonus: Export PPT Speakernotes contain AsciiDoc Automatic export of slides and AsciiDoc 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 44
45. Bonus: Export PPT 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 45
46. docToolchain 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 46
47. Questions? Answers! Thanx for your Attention! 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 47 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 @RalfDMueller https://rdmueller.github.io @docToolchain