Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 4 Treat Docs-as-Code or Docs-like-Code a short History of Docs-as-Code

Slide 5

Slide 5 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 – Convert AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 5

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

build.gradle demo.adoc console output Demo – Convert AsciiDoc http://asciidoctor.org/docs/render-documents/ 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 8

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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.

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

arc42 – a wardrobe for your docs 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 13

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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) ****

Slide 16

Slide 16 text

Diagrams30.05.2018 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 16

Slide 17

Slide 17 text

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!

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

Diagrams: PlantUML 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 19

Slide 20

Slide 20 text

Diagrams: PlantUML 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 20

Slide 21

Slide 21 text

PlantUML Not all types of diagrams are well suited for plantUML. But sequencediagrams are a perfect fit! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 21

Slide 22

Slide 22 text

Diagrams: Don‘t draw – model! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 22

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

=== 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

Slide 26

Slide 26 text

treat Docs-as-Code: automate! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 26

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

Stakeholder 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 28

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

Page Breaks … don‘t make sense for single-page HTML … but for PDF and .docx! <<<< 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 32

Slide 33

Slide 33 text

Collaboration 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 33

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 35

Slide 36

Slide 36 text

Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 36

Slide 37

Slide 37 text

Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 37

Slide 38

Slide 38 text

Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 38

Slide 39

Slide 39 text

Working Together 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 39

Slide 40

Slide 40 text

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 | [email protected] | 555 102 | 40388 | 2 | Erika Mustermann | Scrum Master | [email protected] | 555 103 | 41222 |=== with MS Excel

Slide 41

Slide 41 text

Managing Tables in AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 41

Slide 42

Slide 42 text

Testing 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 42

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

Automated Tests for your Docs https://github.com/aim42/htmlSanityCheck 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 44

Slide 45

Slide 45 text

… coming soon: Linting 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 45 http://www.hemingwayapp.com/ https://github.com/btford/write-good

Slide 46

Slide 46 text

Bonus: Export PPT Speakernotes contain AsciiDoc Automatic export of slides and AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 46

Slide 47

Slide 47 text

Bonus: Export PPT 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 47

Slide 48

Slide 48 text

docToolchain 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 48

Slide 49

Slide 49 text

31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 49 Clipart: presentermedia.com, licenced to [email protected] Questions?

Slide 50

Slide 50 text

31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 50 Clipart: presentermedia.com, licenced to [email protected] Thanx for your Attention!