Upgrade to Pro — share decks privately, control downloads, hide ads and more …

DOCS-AS-CODE, ARC42, ASCIIDOC, GRADLE & CO. IM EINSATZ

DOCS-AS-CODE, ARC42, ASCIIDOC, GRADLE & CO. IM EINSATZ

https://www.jug.ch/html/events/2021/docs-as-code.html

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!

docToolchain: https://doctoolchain.github.io/docToolchain/v2.0.x/

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

April 13, 2021
Tweet

Transcript

  1. Einfach besser dokumentieren DB Systel GmbH | Ralf D. Müller

    | JUG CH | 13.04.2021 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 CH | 13.04.2021 2
  3. Ralf D. Müller, DB Systel

  4. 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 CH | 13.04.2021 4
  5. 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 CH | 13.04.2021 5
  6. arc42 DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 6
  7. 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 CH | 13.04.2021 7
  8. arc42 … … ist das Standard-Template im deutschsprachigen Raum …

    ist verfügbar in Deutsch, Englisch, Spanisch, Russisch & Italienisch … 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 CH | 13.04.2021 8
  9. arc42 – ein Kleiderschrank für Dokumentation DB Systel GmbH |

    Ralf D. Müller | JUG CH | 13.04.2021 9
  10. 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 CH | 13.04.2021 10
  11. 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 CH | 13.04.2021 11
  12. 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 CH | 13.04.2021 12
  13. 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 CH | 13.04.2021 13
  14. Treat Docs-as-Code DB Systel GmbH | Ralf D. Müller |

    JUG CH | 13.04.2021 15
  15. Was ist Docs-as-Code? DB Systel GmbH | Ralf D. Müller

    | JUG CH | 13.04.2021 16 ,--._______,-. ,',' , . ,_`-. / / ,' , _` ``. | ) `-.. (,';'""`/ '"`-._ ` \/ ______ \\ : ,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- :`-- / \_:_:_| ,',',' | |___ \ `^._,--' / , , .) `-._,-'
  16. 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 CH | 13.04.2021 17
  17. 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 CH | 13.04.2021 18
  18. 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 CH | 13.04.2021 19
  19. build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/

    DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 20
  20. 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 CH | 13.04.2021 21
  21. .adoc .adoc …doch die Reise beginnt erst .docx .adoc .html

    DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 22
  22. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html DB

    Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 23
  23. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR

    .adoc DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 24
  24. 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 CH | 13.04.2021 25
  25. The End? DB Systel GmbH | Ralf D. Müller |

    JUG CH | 13.04.2021 26 Danke für Ihre Aufmerksamkeit! Fragen?
  26. Diagramme DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 27
  27. Diagramme http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ Komplexe Diagramme als einfachen Text verwalten DB

    Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 28
  28. PlantUML DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 29
  29. Diagramme: PlantUML DB Systel GmbH | Ralf D. Müller |

    JUG CH | 13.04.2021 30
  30. Diagramme: PlantUML DB Systel GmbH | Ralf D. Müller |

    JUG CH | 13.04.2021 31
  31. Diagrams.net (formerly known as draw.io) DB Systel GmbH | Ralf

    D. Müller | JUG CH | 13.04.2021 32 PNG-Diagramm <xml> … </xml> Meta-Daten
  32. Diagrams.net (formerly known as draw.io) DB Systel GmbH | Ralf

    D. Müller | JUG CH | 13.04.2021 33
  33. Diagramme: Nicht malen, modellieren! DB Systel GmbH | Ralf D.

    Müller | JUG CH | 13.04.2021 34
  34. 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 CH | 13.04.2021 35
  35. 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 CH | 13.04.2021 36
  36. === Stakeholder ==== Users and Groups of Users image::ea/1.5_Stakeholder.png[] |===

    | Role | Description | Goal | Comment include::../../ea/stakeholder.ad[] |=== treat Docs-as-Code: automate! DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 37
  37. treat Docs-as-Code IV: automate DB Systel GmbH | Ralf D.

    Müller | JUG CH | 13.04.2021 38
  38. Stakeholder DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 40
  39. .docx bzw. MS Word http://pandoc.org DB Systel GmbH | Ralf

    D. Müller | JUG CH | 13.04.2021 41
  40. .docx bzw. MS Word DB Systel GmbH | Ralf D.

    Müller | JUG CH | 13.04.2021 42
  41. ...bzw. pdf DB Systel GmbH | Ralf D. Müller |

    JUG CH | 13.04.2021 43
  42. Modulare Dokumentation DB Systel GmbH | Ralf D. Müller |

    JUG CH | 13.04.2021 44 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.ado c include security- master.adoc business- master.adoc
  43. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 45
  44. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 46
  45. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 47
  46. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 48
  47. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 49
  48. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 50
  49. Besser: statische Seiten DB Systel GmbH | Ralf D. Müller

    | JUG CH | 13.04.2021 51
  50. Besser: statische Seiten DB Systel GmbH | Ralf D. Müller

    | JUG CH | 13.04.2021 52
  51. Besser: statische Seiten - DB Systel GmbH | Ralf D.

    Müller | JUG CH | 13.04.2021 53
  52. Besser: statische Seiten - DB Systel GmbH | Ralf D.

    Müller | JUG CH | 13.04.2021 54
  53. Zusammenarbeit - Tabellen DB Systel GmbH | Ralf D. Müller

    | JUG CH | 13.04.2021 55
  54. 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 CH | 13.04.2021 56
  55. Managing Tables in AsciiDoc DB Systel GmbH | Ralf D.

    Müller | JUG CH | 13.04.2021 57
  56. Testing DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 58
  57. Automatisiertes Testing der Doku DB Systel GmbH | Ralf D.

    Müller | JUG CH | 13.04.2021 59 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
  58. Automatisiertes Testing der Doku DB Systel GmbH | Ralf D.

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

    D. Müller | JUG CH | 13.04.2021 61
  60. Static Site Generators DB Systel GmbH | Ralf D. Müller

    | JUG CH | 13.04.2021 62 arc42 Dokumentation Test-Reports Landing-Page Blog User-Manual Suche
  61. Static Site Generators mit AsciiDoc DB Systel GmbH | Ralf

    D. Müller | JUG CH | 13.04.2021 63 Quelle: www.staticgen.com
  62. Landing-Page DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 64
  63. Umfangreiche AsciiDoc-Dokumentation DB Systel GmbH | Ralf D. Müller |

    JUG CH | 13.04.2021 65
  64. News / Blog mit RSS-Feed DB Systel GmbH | Ralf

    D. Müller | JUG CH | 13.04.2021 66
  65. News / Blog mit RSS-Feed DB Systel GmbH | Ralf

    D. Müller | JUG CH | 13.04.2021 67
  66. docToolchain DB Systel GmbH | Ralf D. Müller | JUG

    CH | 13.04.2021 68
  67. DB Systel GmbH | Ralf D. Müller | JUG CH

    | 13.04.2021 69
  68. Danke für Eure Aufmerksamkeit! Thanx to all Contributors and Sponsors!

    jBake docToolchain
  69. None