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

want to give feedback? => https://rdmueller.github.io/feedback

JUG Saxony Day, Radebeul, 13.09.2019,
http://jug-karlsruhe.de/content/docs-as-code/
https://doctoolchain.github.io/docToolchain
https://jaxenter.de/tag/hhgdc
https://docs-as-co.de
https://arc42.org
https://twitter.com/RalfDMueller
https://twitter.com/docToolchain

Der Vortrag zeigt, wie Sie die Qualität Ihrer Dokumentation erhöhen und gleichzeitig den Aufwand zur Pflege reduzieren, indem Sie Ihre Dokumentation genauso wie Ihren Code verwalten und in den Build integrieren. Anhand des Beispiels einer Architekturdokumentation, zeigt Ralf, wie Sie mit dem arc42-Template im AsciiDoc-Format und Gradle als Build-Tool einfach Diagramme in Ihre Dokumentation integrieren, Stakeholder-spezifische Dokumente erzeugen und verschiedene Ausgabeformate generieren. Reviewfähige PDF-Dokumente? Publishing nach Confluence? Integration einer Präsentation? Alles kein Problem! Einige Teile der Doku können Sie sogar automatisiert testen!

Transcript

1. 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
2. Incomplete or confusing documentation #1 Problem with Open Source DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 2
3. 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
4. 4 DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 Digital | bewegen | verstehen | anwenden | begleiten | vernetzen | denken und handeln DB Systel. Digital bewegen. Gemeinsam.
5. 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
6. 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
7. 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
8. 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
9. arc42 DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 9
10. 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
11. 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
12. arc42 – ein Kleiderschrank für Dokumentation DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 12
13. 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
14. 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
15. 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
16. 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
17. 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“
18. Treat Docs-as-Code DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 18
19. 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- :`-- / \_:_:_| ,',',' | |___ \ `^._,--' / , , .) `-._,-'
20. 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
21. 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
22. 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
23. 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
24. 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
25. .adoc .adoc …doch die Reise beginnt erst .docx .adoc .html DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 25
26. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 26
27. 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
28. 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
29. The End? DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 29 Danke für Ihre Aufmerksamkeit! Fragen?
30. Diagramme DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 30
31. 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
32. PlantUML DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 32
33. Diagramme: PlantUML DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 33
34. Diagramme: PlantUML DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 34
35. draw.io DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 35 PNG-Diagramm <xml> … </xml> Meta-Daten
36. draw.io DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 36
37. Diagramme: Nicht malen, modellieren! DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 37
38. 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
39. 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
40. === 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! DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 40
41. treat Docs-as-Code IV: automate DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 41
42. Stakeholder DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 43
43. .docx bzw. MS Word http://pandoc.org DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 44
44. .docx bzw. MS Word DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 45
45. ...bzw. pdf DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 46
46. 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
47. Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 48
48. Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 49
49. Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 50
50. Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 51
51. Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 52
52. Zusammenarbeit DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 53
53. Besser: statische Seiten DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 54
54. Besser: statische Seiten DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 55
55. Besser: statische Seiten - DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 56
56. Besser: statische Seiten - DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 57
57. Zusammenarbeit - Tabellen DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 58
58. 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
59. Managing Tables in AsciiDoc DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 60
60. Testing DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 61
61. 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
62. Automatisiertes Testing der Doku DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 63 https://github.com/aim42/htmlSanityCheck
63. … demnächst: Linting http://www.hemingwayapp.com/ https://github.com/btford/write-good DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 64
64. Static Site Generators DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 65 arc42 Dokumentation Test-Reports Landing-Page Blog User-Manual Suche
65. Static Site Generators mit AsciiDoc DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 66 Quelle: www.staticgen.com
66. Landing-Page DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 67
67. Umfangreiche AsciiDoc-Dokumentation DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 68
68. News / Blog mit RSS-Feed DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 69
69. News / Blog mit RSS-Feed DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 70
70. docToolchain DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 71
71. DB Systel GmbH | @RalfDMueller | JUG Saxony Day | 13.09.2019 72
72. 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