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

Slide 1

Slide 1 text

arc42, AsciiDoc, Gradle & Co. Im Einsatz DB Systel GmbH | Ralf D. Müller | JUG Saxony Day | 13.09.2019 Platzhalter für Titelbild – Hier können Sie Bilder aus der Mediathek einfügen! Placeholder for title picture – You can insert here pictures from the Mediathek! Docs-as-Code

Slide 2

Slide 2 text

Incomplete or confusing documentation #1 Problem with Open Source DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 2

Slide 3

Slide 3 text

Ralf D. Müller Software Architect @ DB Systel mit Schwerpunkt Web-Technologien Qualität (Security, Testautomation) Produktivität (Gradle, Groovy, Grails) Prozessoptimierung In der Freizeit Geek, arc42 Contributor & Maintainer von docToolchain DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 3

Slide 4

Slide 4 text

Slide 5

Slide 5 text

Dr. Gernot Starke – innoQ Fellow Softwarearchitektur Entwurf Evolution + Modernisierung Dokumentation Reviews +49 177 7282570 gernot.starke@innoq.com DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 5

Slide 6

Slide 6 text

Was machen wir die nächsten 60 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 DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 6

Slide 7

Slide 7 text

VEry NOrMal System Gewachsene Dokumentation Unterschiedliche Stakeholder Aufgrund verschiedener Änderungen stets im Wandel Hoher Pflegeaufwand Das VENOM Projekt DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 7

Slide 8

Slide 8 text

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 DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 8

Slide 9

Slide 9 text

arc42 DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 9

Slide 10

Slide 10 text

Heutiger Fokus: Architektur Docs-as-Code Wie schreibe ich eine System-Dokumentation? Dr. Peter Hruschka http://www.peterhruschka.eu/ Dr. Gernot Starke http://gernotstarke.de/ http://arc42.org/ DAS Template für die Dokumentation eines Software Systems. DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 10

Slide 11

Slide 11 text

arc42 … … ist das Standard-Template im deutschsprachigen Raum … ist verfügbar in Deutsch, Englisch und Spanisch und Russisch … ist verfügbar in > 9 Formaten (.adoc, .docx, .rst, .md, .tex …) … gibt der Dokumentation eine einheitliche Struktur … ist verfügbar mit und ohne Hilfestellung … hilft die richtigen Aspekte richtig zu dokumentieren DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 11

Slide 12

Slide 12 text

arc42 – ein Kleiderschrank für Dokumentation DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 12

Slide 13

Slide 13 text

arc42 – ein Kleiderschrank für Dokumentation 1. Requirements & Goals 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 DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 13

Slide 14

Slide 14 text

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 AsciiDoc DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 14

Slide 15

Slide 15 text

Blick in das Template Randbedingungen Inhalt Randbedingungen und Vorgaben, die ihre Freiheiten bezüglich Entwurf, Implementierung oder Ihres Entwicklungsprozesses einschränken. Diese Randbedingungen gelten manchmal organisations- oder firmenweit über die Grenzen einzelner Systeme hinweg. Motivation Für eine tragfähige Architektur sollten Sie genau wissen, wo Ihre Freiheitsgrade bezüglich der Entwurfsentscheidungen liegen und wo Sie Randbedingungen beachten müssen. Sie können Randbedingungen vielleicht noch verhandeln, zunächst sind sie aber da. Form Einfache Tabellen der Randbedingungen mit Erläuterungen. Bei Bedarf unterscheiden Sie technische, organisatorische und politische Randbedingungen oder übergreifende Konventionen (beispielsweise Programmier- oder Versionierungsrichtlinien, Dokumentations- oder Namenskonvention). DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 15

Slide 16

Slide 16 text

arc42 als AsciiDoc Template == Randbedingungen [role="arc42help"] **** .Inhalt Randbedingungen und Vorgaben, die ihre Freiheiten bezüglich Entwurf, Implementierung oder Ihres Entwicklungsprozesses einschränken. Diese Randbedingungen gelten manchmal organisations- oder firmenweit über die Grenzen einzelner Systeme hinweg. .Motivation Für eine tragfähige Architektur sollten Sie genau wissen, wo Ihre Freiheitsgrade bezüglich der Entwurfsentscheidungen liegen und wo Sie Randbedingungen beachten müssen. Sie können Randbedingungen vielleicht noch verhandeln, zunächst sind sie aber da. .Form Einfache Tabellen der Randbedingungen mit Erläuterungen. Bei Bedarf unterscheiden Sie technische, organisatorische und politische Randbedingungen oder übergreifende Konventionen (beispielsweise Programmier- oder Versionierungsrichtlinien, Dokumentations- oder Namenskonvention). **** DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 16

Slide 17

Slide 17 text

arc42 Formate DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 17 AsciiDoc ist aus unserer Sicht das flexibelste Format Da es in alle anderen Formate (fast verlustfrei) gewandelt werden kann, gibt es immer „Plan B“

Slide 18

Slide 18 text

Treat Docs-as-Code DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 18

Slide 19

Slide 19 text

Was ist Docs-as-Code? DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 19 ,--._______,-. ,',' , . ,_`-. / / ,' , _` ``. | ) `-.. (,';'""`/ '"`-._ ` \/ ______ \\ : ,o.-`- ,o. )\` -' `---.)) : , d8b ^-. '| `. ` `. |/ __:_ `. | , ` ` \ | ( ,-.`-. ;' ; ` : ; | | , `. / ; : \ ;-'`:::._,`.__),' : ; / , `- `-- ; | / \ ` , | ( ` : : ,\ | \ `. : : : ,' \ : \ `|-- ` \ ,' ,-' :-.-'; : |`--.______; | : : : / | | | \ | ; ; ; / ; _/--' | -hrr- :`-- / \_:_:_| ,',',' | |___ \ `^._,--' / , , .) `-._,-' ------------------------------------------------ This ASCII pic can be found at https://asciiart.website/index.php?art=animals/dogs ,--._______,-. ,',' , . ,_`-. / / ,' , _` ``. | ) `-.. (,';'""`/ '"`-._ ` \/ ______ \\ : ,o.-`- ,o. )\` -' `---.)) : , d8b ^-. '| `. ` `. |/ __:_ `. | , ` ` \ | ( ,-.`-. ;' ; ` : ; | | , `. / ; : \ ;-'`:::._,`.__),' : ; / , `- `-- ; | / \ ` , | ( ` : : ,\ | \ `. : : : ,' \ : \ `|-- ` \ ,' ,-' :-.-'; : |`--.______; | : : : / | | | \ | ; ; ; / ; _/--' | -hrr- :`-- / \_:_:_| ,',',' | |___ \ `^._,--' / , , .) `-._,-' ,--._______,-. ,',' , . ,_`-. / / ,' , _` ``. | ) `-.. (,';'""`/ '"`-._ ` \/ ______ \\ : ,o.-`- ,o. )\` -' `---.)) : , d8b ^-. '| `. ` `. |/ __:_ `. | , ` ` \ | ( ,-.`-. ;' ; ` : ; | | , `. / ; : \ ;-'`:::._,`.__),' : ; / , `- `-- ; | / \ ` , | ( ` : : ,\ | \ `. : : : ,' \ : \ `|-- ` \ ,' ,-' :-.-'; : |`--.______; | : : : / | | | \ | ; ; ; / ; _/--' | -hrr- :`-- / \_:_:_| ,',',' | |___ \ `^._,--' / , , .) `-._,-'

Slide 20

Slide 20 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 – eine erste Konvertierung DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 20

Slide 21

Slide 21 text

demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3" } Demo – eine erste Konvertierung DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 21

Slide 22

Slide 22 text

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 DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 22

Slide 23

Slide 23 text

build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/ DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 23

Slide 24

Slide 24 text

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 DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 24

Slide 25

Slide 25 text

.adoc .adoc …doch die Reise beginnt erst .docx .adoc .html DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 25

Slide 26

Slide 26 text

treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 26

Slide 27

Slide 27 text

treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR .adoc DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 27

Slide 28

Slide 28 text

treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR .adoc Build- Server On Change Publish DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 28

Slide 29

Slide 29 text

The End? DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 29 Danke für Ihre Aufmerksamkeit! Fragen?

Slide 30

Slide 30 text

Diagramme DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 30

Slide 31

Slide 31 text

Diagramme http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ Komplexe Diagramme als einfachen Text verwalten DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 31

Slide 32

Slide 32 text

PlantUML DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 32

Slide 33

Slide 33 text

Diagramme: PlantUML DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 33

Slide 34

Slide 34 text

Diagramme: PlantUML DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 34

Slide 35

Slide 35 text

draw.io DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 35 PNG-Diagramm … Meta-Daten

Slide 36

Slide 36 text

draw.io DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 36

Slide 37

Slide 37 text

Diagramme: Nicht malen, modellieren! DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 37

Slide 38

Slide 38 text

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. DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 38

Slide 39

Slide 39 text

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. DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 39

Slide 40

Slide 40 text

Slide 41

Slide 41 text

treat Docs-as-Code IV: automate DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 41

Slide 42

Slide 42 text

Stakeholder DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 43

Slide 43

Slide 43 text

.docx bzw. MS Word http://pandoc.org DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 44

Slide 44

Slide 44 text

.docx bzw. MS Word DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 45

Slide 45

Slide 45 text

...bzw. pdf DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 46

Slide 46

Slide 46 text

Modulare Dokumentation DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 47 arc42- master.adoc kapitel1.adoc kapitel2.adoc public class HelloWorld { public static void main (String[] args) { // Ausgabe Hello World! System.out.println("Hello World!"); } } include include include kapitel8.adoc kapitel8.1.adoc include security- master.adoc business- master.adoc

Slide 47

Slide 47 text

Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 48

Slide 48

Slide 48 text

Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 49

Slide 49

Slide 49 text

Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 50

Slide 50

Slide 50 text

Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 51

Slide 51

Slide 51 text

Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 52

Slide 52

Slide 52 text

Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 53

Slide 53

Slide 53 text

Besser: statische Seiten DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 54

Slide 54

Slide 54 text

Besser: statische Seiten DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 55

Slide 55

Slide 55 text

Besser: statische Seiten - DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 56

Slide 56

Slide 56 text

Besser: statische Seiten - DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 57

Slide 57

Slide 57 text

Zusammenarbeit - Tabellen DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 58

Slide 58

Slide 58 text

Tabellen in AsciiDoc [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 |=== mit MS Excel! DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 59

Slide 59

Slide 59 text

Managing Tables in AsciiDoc DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 60

Slide 60

Slide 60 text

Testing DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 61

Slide 61

Slide 61 text

Automatisiertes Testing der Doku DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 62 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

Slide 62

Slide 62 text

Automatisiertes Testing der Doku DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 63 https://github.com/aim42/htmlSanityCheck

Slide 63

Slide 63 text

… demnächst: Linting http://www.hemingwayapp.com/ https://github.com/btford/write-good DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 64

Slide 64

Slide 64 text

Static Site Generators DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 65 arc42 Dokumentation Test-Reports Landing-Page Blog User-Manual Suche

Slide 65

Slide 65 text

Static Site Generators mit AsciiDoc DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 66 Quelle: www.staticgen.com

Slide 66

Slide 66 text

Landing-Page DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 67

Slide 67

Slide 67 text

Umfangreiche AsciiDoc-Dokumentation DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 68

Slide 68

Slide 68 text

News / Blog mit RSS-Feed DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 69

Slide 69

Slide 69 text

News / Blog mit RSS-Feed DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 70

Slide 70

Slide 70 text

docToolchain DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 71

Slide 71

Slide 71 text

DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 72

Slide 72

Slide 72 text

Vielen Dank für Ihre Aufmerksamkeit! Ralf.D.Mueller@DeutscheBahn.com https://docs-as-co.de @docToolchain Image-Credits: Title - Photo by Susan Yin on Unsplash Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com www.dbsystel.de https://rdmueller.github.io/feedback