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

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

18.02.2020, Java User Group Erfurt
https://www.meetup.com/de-DE/devopsthde/events/268055746/

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 Du die Qualität Deiner Dokumentation erhöhst und gleichzeitig den Aufwand zur Pflege reduzierst, indem Du Deine Dokumentation genauso wie Deinen Code verwaltest und in den Build integrierst. Anhand des Beispiels einer Architekturdokumentation, zeigt Ralf, wie Du mit dem arc42-Template im AsciiDoc-Format und Gradle als Build-Tool einfach Diagramme in Ihre Dokumentation integrierst, Stakeholder-spezifische Dokumente erzeugst und verschiedene Ausgabeformate generierst. Reviewfähige PDF-Dokumente? Publishing nach Confluence? Integration einer Präsentation? Alles kein Problem! Einige Teile der Doku kannst Du sogar automatisiert testen!

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

February 18, 2020
Tweet

Transcript

  1. arc42, AsciiDoc, Gradle & Co. Im Einsatz DB Systel GmbH

    | Ralf D. Müller | JUG Erfurt | 18.02.2020 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 3
  4. Dr. Gernot Starke – innoQ Fellow Softwarearchitektur Entwurf Evolution +

    Modernisierung Dokumentation Reviews +49 177 7282570 gernot.starke@innoq.com DB Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 4
  5. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 5
  6. VEry NOrMal System Gewachsene Dokumentation Unterschiedliche Stakeholder Aufgrund verschiedener Änderungen

    stets im Wandel Hoher Pflegeaufwand Das VENOM Projekt DB Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 6
  7. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 7
  8. arc42 DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 8
  9. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 9
  10. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 10
  11. arc42 – ein Kleiderschrank für Dokumentation DB Systel GmbH |

    Ralf D. Müller | JUG Erfurt | 18.02.2020 11
  12. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 12
  13. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 13
  14. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 14
  15. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 15
  16. arc42 Formate DB Systel GmbH | Ralf D. Müller |

    JUG Erfurt | 18.02.2020 16 AsciiDoc ist aus unserer Sicht das flexibelste Format Da es in alle anderen Formate (fast verlustfrei) gewandelt werden kann, gibt es immer „Plan B“
  17. Treat Docs-as-Code DB Systel GmbH | Ralf D. Müller |

    JUG Erfurt | 18.02.2020 17
  18. Was ist Docs-as-Code? DB Systel GmbH | Ralf D. Müller

    | JUG Erfurt | 18.02.2020 18 ,--._______,-. ,',' , . ,_`-. / / ,' , _` ``. | ) `-.. (,';'""`/ '"`-._ ` \/ ______ \\ : ,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- :`-- / \_:_:_| ,',',' | |___ \ `^._,--' / , , .) `-._,-'
  19. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 19
  20. demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3"

    } Demo – eine erste Konvertierung DB Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 20
  21. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 21
  22. build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/

    DB Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 22
  23. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 23
  24. .adoc .adoc …doch die Reise beginnt erst .docx .adoc .html

    DB Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 24
  25. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html DB

    Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 25
  26. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR

    .adoc DB Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 26
  27. treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR

    .adoc Build- Server On Change Publish DB Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 27
  28. The End? DB Systel GmbH | Ralf D. Müller |

    JUG Erfurt | 18.02.2020 28 Danke für Ihre Aufmerksamkeit! Fragen?
  29. Diagramme DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 29
  30. Diagramme http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ Komplexe Diagramme als einfachen Text verwalten DB

    Systel GmbH | Ralf D. Müller | JUG Erfurt | 18.02.2020 30
  31. PlantUML DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 31
  32. Diagramme: PlantUML DB Systel GmbH | Ralf D. Müller |

    JUG Erfurt | 18.02.2020 32
  33. Diagramme: PlantUML DB Systel GmbH | Ralf D. Müller |

    JUG Erfurt | 18.02.2020 33
  34. draw.io DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 34 PNG-Diagramm <xml> … </xml> Meta-Daten
  35. draw.io DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 35
  36. Diagramme: Nicht malen, modellieren! DB Systel GmbH | Ralf D.

    Müller | JUG Erfurt | 18.02.2020 36
  37. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 37
  38. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 38
  39. === 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 39
  40. treat Docs-as-Code IV: automate DB Systel GmbH | Ralf D.

    Müller | JUG Erfurt | 18.02.2020 40
  41. Stakeholder DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 42
  42. .docx bzw. MS Word http://pandoc.org DB Systel GmbH | Ralf

    D. Müller | JUG Erfurt | 18.02.2020 43
  43. .docx bzw. MS Word DB Systel GmbH | Ralf D.

    Müller | JUG Erfurt | 18.02.2020 44
  44. ...bzw. pdf DB Systel GmbH | Ralf D. Müller |

    JUG Erfurt | 18.02.2020 45
  45. Modulare Dokumentation DB Systel GmbH | Ralf D. Müller |

    JUG Erfurt | 18.02.2020 46 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
  46. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 47
  47. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 48
  48. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 49
  49. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 50
  50. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 51
  51. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 52
  52. Besser: statische Seiten DB Systel GmbH | Ralf D. Müller

    | JUG Erfurt | 18.02.2020 53
  53. Besser: statische Seiten DB Systel GmbH | Ralf D. Müller

    | JUG Erfurt | 18.02.2020 54
  54. Besser: statische Seiten - DB Systel GmbH | Ralf D.

    Müller | JUG Erfurt | 18.02.2020 55
  55. Besser: statische Seiten - DB Systel GmbH | Ralf D.

    Müller | JUG Erfurt | 18.02.2020 56
  56. Zusammenarbeit - Tabellen DB Systel GmbH | Ralf D. Müller

    | JUG Erfurt | 18.02.2020 57
  57. 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 | Ralf D. Müller | JUG Erfurt | 18.02.2020 58
  58. Managing Tables in AsciiDoc DB Systel GmbH | Ralf D.

    Müller | JUG Erfurt | 18.02.2020 59
  59. Testing DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 60
  60. Automatisiertes Testing der Doku DB Systel GmbH | Ralf D.

    Müller | JUG Erfurt | 18.02.2020 61 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
  61. Automatisiertes Testing der Doku DB Systel GmbH | Ralf D.

    Müller | JUG Erfurt | 18.02.2020 62 https://github.com/aim42/htmlSanityCheck
  62. … demnächst: Linting http://www.hemingwayapp.com/ https://github.com/btford/write-good DB Systel GmbH | Ralf

    D. Müller | JUG Erfurt | 18.02.2020 63
  63. Static Site Generators DB Systel GmbH | Ralf D. Müller

    | JUG Erfurt | 18.02.2020 64 arc42 Dokumentation Test-Reports Landing-Page Blog User-Manual Suche
  64. Static Site Generators mit AsciiDoc DB Systel GmbH | Ralf

    D. Müller | JUG Erfurt | 18.02.2020 65 Quelle: www.staticgen.com
  65. Landing-Page DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 66
  66. Umfangreiche AsciiDoc-Dokumentation DB Systel GmbH | Ralf D. Müller |

    JUG Erfurt | 18.02.2020 67
  67. News / Blog mit RSS-Feed DB Systel GmbH | Ralf

    D. Müller | JUG Erfurt | 18.02.2020 68
  68. News / Blog mit RSS-Feed DB Systel GmbH | Ralf

    D. Müller | JUG Erfurt | 18.02.2020 69
  69. docToolchain DB Systel GmbH | Ralf D. Müller | JUG

    Erfurt | 18.02.2020 70
  70. DB Systel GmbH | Ralf D. Müller | JUG Erfurt

    | 18.02.2020 71
  71. 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