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

Docs as Code, arc42, AsciiDoc, Gradle und Antora im Einsatz

Docs as Code, arc42, AsciiDoc, Gradle und Antora im Einsatz

JAX Mainz, 08.05.2019, https://jax.de/software-architecture/docs-as-code-arc42-asciidoc-gradle-und-antora-im-einsatz/

Laut mehrerer Umfragen ist fehlende Dokumentation ein großes Hindernis für den Einsatz von Open-Source-Software. In diesem Vortrag wird gezeigt, wie Sie einfach für Ihr Produkt, egal ob Open oder Inner Source, verschiedene Arten von Dokumenationen erzeugen. Dazu werden die gleichen Tools und Ansätze verwendet, wie sie schon zur Entwicklung des Codes Ihres Produkts eingesetzt werden. Damit können Sie die Qualität Ihrer Dokumentation erhöhen und gleichzeitig den Aufwand zur Pflege reduzieren. 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, stakeholderspezifische Dokumente erzeugen und verschiedene Ausgabeformate generieren. Zum Schluss werden die Dokumente noch zu einer hübschen Website zusammengeführt.

https://docs-as-co.de

https://www.dbsystel.de/

Ralf D. Müller

May 08, 2019
Tweet

More Decks by Ralf D. Müller

Other Decks in Programming

Transcript

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

    | Ralf D. Müller | JAX 2019 | Mainz | 08.05.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 | Ralf D. Müller | JAX 2019 | Mainz | 08.05.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 | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 3
  4. Dr. Gernot Starke – innoQ Fellow Softwarearchitektur Entwurf Evolution +

    Modernisierung Dokumentation Reviews +49 177 7282570 [email protected] DB Systel GmbH | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 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 | JAX 2019 | Mainz | 08.05.2019 5
  6. VEry NOrMal System Gewachsene Dokumentation Unterschiedliche Stakholder Aufgrund verschiedener Änderungen

    stets im Wandel Hoher Pflegeaufwand Das VENOM Projekt DB Systel GmbH | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 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 | JAX 2019 | Mainz | 08.05.2019 7
  8. arc42 DB Systel GmbH | Ralf D. Müller | JAX

    2019 | Mainz | 08.05.2019 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 | JAX 2019 | Mainz | 08.05.2019 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 | JAX 2019 | Mainz | 08.05.2019 10
  11. arc42 – ein Kleiderschrank für Dokumentation DB Systel GmbH |

    Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 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 | JAX 2019 | Mainz | 08.05.2019 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 | JAX 2019 | Mainz | 08.05.2019 13
  14. arc42 als AsciiDoc Template == 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) **** DB Systel GmbH | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 14
  15. arc42 Formate DB Systel GmbH | Ralf D. Müller |

    JAX 2019 | Mainz | 08.05.2019 15 AsciiDoc ist aus unserer Sicht das flexibelste Format Da es in alle anderen Formate (fast verlustfrei) gewandelt werden kann, gibt es immer „Plan B“
  16. Was ist Docs-as-Code? DB Systel GmbH | Ralf D. Müller

    | JAX 2019 | Mainz | 08.05.2019 17 ,--._______,-. ,',' , . ,_`-. / / ,' , _` ``. | ) `-.. (,';'""`/ '"`-._ ` \/ ______ \\ : ,o.-`- ,o. )\` -' `---.)) : , d8b ^-. '| `. ` `. |/ __:_ `. | , ` ` \ | ( ,-.`-. ;' ; ` : ; | | , `. / ; : \ ;-'`:::._,`.__),' : ; / , `- `-- ; | / \ ` , | ( ` : : ,\ | \ `. : : : ,' \ : \ `|-- ` \ ,' ,-' :-.-'; : |`--.______; | : : : / | | | \ | ; ; ; / ; _/--' | -hrr- :`-- / \_:_:_| ,',',' | |___ \ `^._,--' / , , .) `-._,-' ------------------------------------------------ This ASCII pic can be found at https://asciiart.website/index.php?art=animals/dogs
  17. 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 | JAX 2019 | Mainz | 08.05.2019 18
  18. 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 | JAX 2019 | Mainz | 08.05.2019 19
  19. 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 | JAX 2019 | Mainz | 08.05.2019 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 | JAX 2019 | Mainz | 08.05.2019 22
  21. .adoc .adoc …doch die Reise beginnt erst .docx .adoc .html

    DB Systel GmbH | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 23
  22. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html DB

    Systel GmbH | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 24
  23. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR

    .adoc DB Systel GmbH | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 25
  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 | JAX 2019 | Mainz | 08.05.2019 26
  25. The End? DB Systel GmbH | Ralf D. Müller |

    JAX 2019 | Mainz | 08.05.2019 27 Danke für Ihre Aufmerksamkeit! Fragen?
  26. draw.io DB Systel GmbH | Ralf D. Müller | JAX

    2019 | Mainz | 08.05.2019 33 PNG-Diagramm <xml> … </xml> Meta-Daten
  27. draw.io DB Systel GmbH | Ralf D. Müller | JAX

    2019 | Mainz | 08.05.2019 34
  28. Diagramme: Nicht malen, modellieren! DB Systel GmbH | Ralf D.

    Müller | JAX 2019 | Mainz | 08.05.2019 35
  29. 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 | JAX 2019 | Mainz | 08.05.2019 36
  30. 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 | JAX 2019 | Mainz | 08.05.2019 37
  31. === 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 | JAX 2019 | Mainz | 08.05.2019 38
  32. treat Docs-as-Code IV: automate DB Systel GmbH | Ralf D.

    Müller | JAX 2019 | Mainz | 08.05.2019 39
  33. 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 Diagramme DB Systel GmbH | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 40
  34. .docx bzw. MS Word http://pandoc.org DB Systel GmbH | Ralf

    D. Müller | JAX 2019 | Mainz | 08.05.2019 42
  35. .docx bzw. MS Word DB Systel GmbH | Ralf D.

    Müller | JAX 2019 | Mainz | 08.05.2019 43
  36. ...bzw. pdf DB Systel GmbH | Ralf D. Müller |

    JAX 2019 | Mainz | 08.05.2019 44
  37. Modulare Dokumentation DB Systel GmbH | Ralf D. Müller |

    JAX 2019 | Mainz | 08.05.2019 45 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
  38. Besser: statische Seiten - DB Systel GmbH | Ralf D.

    Müller | JAX 2019 | Mainz | 08.05.2019 54
  39. Besser: statische Seiten - DB Systel GmbH | Ralf D.

    Müller | JAX 2019 | Mainz | 08.05.2019 55
  40. Tabellen in AsciiDoc [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 |=== mit MS Excel! DB Systel GmbH | Ralf D. Müller | JAX 2019 | Mainz | 08.05.2019 57
  41. Managing Tables in AsciiDoc DB Systel GmbH | Ralf D.

    Müller | JAX 2019 | Mainz | 08.05.2019 58
  42. Testing DB Systel GmbH | Ralf D. Müller | JAX

    2019 | Mainz | 08.05.2019 59
  43. Automatisiertes Testing der Doku DB Systel GmbH | Ralf D.

    Müller | JAX 2019 | Mainz | 08.05.2019 60 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
  44. Automatisiertes Testing der Doku DB Systel GmbH | Ralf D.

    Müller | JAX 2019 | Mainz | 08.05.2019 61 https://github.com/aim42/htmlSanityCheck
  45. Static Site Generators DB Systel GmbH | Ralf D. Müller

    | JAX 2019 | Mainz | 08.05.2019 63 arc42 Dokumentation Test-Reports Landing-Page Blog User-Manual Suche
  46. Static Site Generators mit AsciiDoc DB Systel GmbH | Ralf

    D. Müller | JAX 2019 | Mainz | 08.05.2019 64 Quelle: www.staticgen.com
  47. Unsere Talks auf der JAX 67 Mittwoch, 15:15, Rheingoldhalle Forum

    West Docs as Code: arc42, AsciiDoc und Gradle im Einsatz Montag, 11:00, Rheingoldhalle Gutenberg 2+3 DevOps im Konzern – Autonomie von DevOps- Teams vs. Betriebssicherheit Ralf Müller DB Systel GmbH | Thomas Kappatsch Johannes Dienst (@JohannesDienst) Johannes Dienst Thomas Kappatsch
  48. Vielen Dank für Ihre Aufmerksamkeit! https://docs-as-co.de @docToolchain Image-Credits: Title -

    Photo by Susan Yin on Unsplash Clipart: presentermedia.com, licenced to [email protected] www.dbsystel.de