Docs-as-Code - Architekturdokumentation leicht gemacht

Docs-as-Code - Architekturdokumentation leicht gemacht

Vortrag vom 26.04.2018 auf der JAX Mainz mit Falk Sippach

https://jax.de/software-architecture/the-hitchhikers-guide-to-docs-as-code/

https://doctoolchain.github.io
https://doctoolchain.github.io/docToolchain
https://jaxenter.de/tag/hhgdc
https://docs-as-co.de
https://arc42.org
https://rdmueller.github.io
https://twitter.com/RalfDMueller
https://twitter.com/docToolchain

Technische Dokumentation sollte man nicht mit Textverarbeitungsprogrammen erzeugen. Stattdessen ergibt es Sinn, die Erstellung in die normalen Entwicklungsprozesse einzubeziehen, sie zu automatisieren (Continuous Documentation) und mit den typischen Werkzeugen der Entwickler sowie mittels leichtgewichtigen Textformaten zu bearbeiten (Documentation as Code).

Anhand einer Architekturdokumentation zeigen wir, 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. Zwischendurch bekommen Sie zahlreiche Tipps, wie und wo Sie systematisch den Aufwand für Dokumentation reduzieren können und trotzdem lesbare, verständliche und praxistaugliche Ergebnisse produzieren. Dokumentieren soll endlich auch Spaß machen.

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

April 26, 2018
Tweet

Transcript

  1. 2.

    Ralf D. Müller Bei Tag Solution Architect in der Digital

    Factory der Deutschen Bank. In der Freizeit Geek mit Schwerpunkt Web-Technologien Qualität (Security, Testautomation) Produktivität (Gradle, Groovy, Grails) Maintainer von docToolchain 26.04.2018 @RalfDMueller @sippsack @docToolchain 2
  2. 3.

    Falk Sippach Orientation in Objects GmbH Trainer, Berater, Entwickler in

    Mannheim. JUG Darmstadt Co-Organisator Committer DukeCon Konferenzplaner 26.04.2018 @RalfDMueller @sippsack @docToolchain 3
  3. 4.

    Was machen wir die nächsten 50 Minuten? Was ist docs-as-code?

    Warum docs-as-code? Wie kann docs-as-code umgesetzt werden? Experimentelle Features :-) Vorschläge aus Erfahrung, keine Silver Bullet 26.04.2018 @RalfDMueller @sippsack @docToolchain 4
  4. 5.

    Architektur dokumentieren? 26.04.2018 @RalfDMueller @sippsack @docToolchain 5 Anforderungen klären Architektur

    entwerfen Architektur bewerten aus: Effektive Softwarearchitekturen (G. Starke + P. Hruschka) Architektur kommunizieren
  5. 6.

    Warum dokumentieren? 26.04.2018 @RalfDMueller @sippsack @docToolchain 6 Grafik von The

    Practical Dev: https://github.com/thepracticaldev/orly-full-res/blob/master/notwritingdocs-big.png (CC0 Public Domain Lizenz) Entwurfsunterstützung Kommunikation Bewertbarkeit Frage nach Warum Neue Mitarbeiter
  6. 7.

    Dokumentieren nervt! Falsche Werkzeuge (WYSIWYG) Dateiablage im Share-Laufwerk Redundanzen Textwüste

    Handarbeit Veraltet Liest sowieso keiner! 26.04.2018 @RalfDMueller @sippsack @docToolchain 7
  7. 9.

    WYSIWYG Tools 26.04.2018 @RalfDMueller @sippsack @docToolchain 9 Foto von Antranias:

    https://pixabay.com/en/telescope-view-distant-binoculars-1201497/ (CC0 Public Domain Lizenz) Textverarbeitung Visio Powerpoint UML-Tools
  8. 11.

    Ein Bild sagt mehr als 1000 Worte … 26.04.2018 @RalfDMueller

    @sippsack @docToolchain 11 Erstellen mit Grafik-Tools • yEd, UML-Tools, … • Einbetten in Markup Erstellen in Textformaten • PlantUML, ditaa, …
  9. 13.

    Unser täglich Brot … 26.04.2018 @RalfDMueller @sippsack @docToolchain 13 Foto

    von geralt: https://pixabay.com/de/unternehmer-start-start-up-karriere-696976/ (CC0 Public Domain Lizenz) Plain-Text Texteditor/IDE Kommandozeile Buildwerkzeuge Versionsverwaltung
  10. 14.

    Documentation as Code 26.04.2018 @RalfDMueller @sippsack @docToolchain 14 Foto von

    ahobbit: https://pixabay.com/en/vault-business-bank-vault-bank-1144249/ (CC0 Public Domain Lizenz) Code-Nähe Ablage im Repo Versionier-/diffbar Synchrone Auslieferung Offlinefähig Teil des Build-Prozess Generierung Automatisierung Flexible Ausgabeformate
  11. 15.

    Redundanzen vermeiden 26.04.2018 @RalfDMueller @sippsack @docToolchain 15 Foto von pcdazero:

    https://pixabay.com/en/umbrellas-sea-holiday-summer-beach-921501/ (CC0 Public Domain Lizenz) Includes Quellcode verlinken Platzhalter einbetten Inhalte generieren: • WSDL, Swagger DB-Schema Annotationen JavaDoc Markup generieren
  12. 16.

    Continuous Documentation 26.04.2018 @RalfDMueller @sippsack @docToolchain 16 Foto von Ted

    Van Pelt: https://www.flickr.com/photos/bantam10/5209157298 (CC BY 2.0 Lizenz) Agile Projekte: • iterativ • kontinuierlich Dokumentation: • automatisiert erstellen • regelmässig ergänzen • reviewen, nachbessern
  13. 18.

    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 26.04.2018 @RalfDMueller @sippsack @docToolchain 18
  14. 19.

    demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3"

    } Demo – eine erste Konvertierung 26.04.2018 @RalfDMueller @sippsack @docToolchain 19
  15. 20.

    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 26.04.2018 @RalfDMueller @sippsack @docToolchain 20
  16. 22.

    Out-of-the-Box Features „ablenkungsfrei“ – Dokumentation wie eMails schreiben Gliederung in

    Unterdokumente Neugliederung je nach Stakeholder Bilder werden referenziert, nicht eingebettet leichte Versionierung „treat Docs-as-Code“ Formatierung von Source-Code Reviews, Pull-Requests, Versionierung durch Git Konvertierung nach HTML5 und DocBook 26.04.2018 @RalfDMueller @sippsack @docToolchain 22
  17. 24.

    arc42 … 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 24 … ist das

    Standard-Template im deutschsprachigen Raum … ist verfügbar in Deutsch, Englisch und Spanisch … is verfügbar in 9 Formaten (.adoc, .docx, .rst, .md, .tex …) … gibt Ihrer Architekturdokumentation eine Structure … ist verfügbar mit und ohne Hilfe
  18. 26.

    arc42 – eher Kleiderschrank als Formular 1. Requirements & Goals

    17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 26 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
  19. 27.

    arc42 als AsciiDoc Template 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 27 ==

    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) ****
  20. 29.

    treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR

    .adoc 26.04.2018 @RalfDMueller @sippsack @docToolchain 29
  21. 30.

    treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR

    .adoc Build- Server On Change Publish 26.04.2018 @RalfDMueller @sippsack @docToolchain 30
  22. 34.

    Diagramme: PlantUML .Benutzer und Benutzergruppen von VENOM [plantuml] ---- !pragma

    graphviz_dot jdot (VENOM\ni.B.O.S.S) as venom "Private User" -right-> venom "User Groups" --> venom "Corporate Users" --> venom "Government Users" -up-> venom "Regulation &\nStandard Bodies" -up-> venom "Operations" --> venom "Internal Users" -left-> venom ---- 26.04.2018 @RalfDMueller @sippsack @docToolchain 34
  23. 35.

    PlantUML Nicht alle Diagrammtypen sind für PlantUML gleichgut geeignet. Sequenzdiagramme

    sind jedoch ein sehr guter Anwendungsfall! 26.04.2018 @RalfDMueller @sippsack @docToolchain 35
  24. 38.

    PlantUML $ java -jar plantuml.jar -metadata activity.png 26.04.2018 @RalfDMueller @sippsack

    @docToolchain 38 http://mrhaki.blogspot.de/search/label/PlantUML
  25. 40.

    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. 26.04.2018 @RalfDMueller @sippsack @docToolchain 40
  26. 41.

    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. 26.04.2018 @RalfDMueller @sippsack @docToolchain 41
  27. 42.

    === Stakeholder ==== Benutzer und Benutzergruppen [[figure-users]] image::ea/1.5_Stakeholder.png[title="Benutzer und Benutzergruppen

    von VENOM"] [cols="2,3,3,2" options="header"] .Benutzer und Benutzergruppen |=== | Rolle | Beschreibung | Ziel | Bemerkungen include::../../ea/stakeholder.ad[] |=== treat Docs-as-Code IV: automate 26.04.2018 @RalfDMueller @sippsack @docToolchain 42
  28. 44.

    Diagramme Noch keinen eigenen Stil gefunden? => C4 von Simon

    Brown ist ein guter Start https://c4model.com/ Context, Containers, Components, Classes 26.04.2018 @RalfDMueller @sippsack @docToolchain 44
  29. 54.

    Managing Tables in AsciiDoc 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 54 [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 |=== with MS Excel
  30. 57.

    Automatisiertes Testing der Doku 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 26.04.2018 @RalfDMueller @sippsack @docToolchain 57
  31. 60.

    Bonus: Export PPT ▪Sprechernotizen enthalten asciidoc ▪Slides und asciidoc werden

    automatisch exportiert 26.04.2018 @RalfDMueller @sippsack @docToolchain 60
  32. 65.

    PlantUML zu jQAssistant-Regel 26.04.2018 @RalfDMueller @sippsack @docToolchain 65 Architektur- definition

    in PlantUML Generierte Cypher- Regel [[architecture:DefinedDependencies] [plantuml,role=concept] ---- [artifactId:xo.impl] as impl <<:Maven:Project>> [artifactId:xo.api] as api <<:Maven:Project>> [artifactId:xo.spi] as spi <<:Maven:Project>> impl -> api : Defines Dependency impl -> spi : Defines Dependency spi -> api : Defines Dependency ---- [[architecture:UndefinedDependenci [source,cypher,role=constraint,requir There must not be dependencies bet ---- MATCH (p1:Maven:Project)-[:CREATES]->(:A (p2:Maven:Project)-[:CREATES]->(:A (t2)-[:DEPENDS_ON]->(t1) WHERE NOT (p1)-[:DEFINES_DEPENDENCY]->(p2 RETURN * ----
  33. 67.

    Fragen? Antworten! 26.04.2018 @RalfDMueller @sippsack @docToolchain 67 https://doctoolchain.github.io https://jaxenter.de/tag/hhgdc https://docs-as-co.de

    https://arc42.org Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com Ralf.D.Mueller@gmail.com @RalfDMueller https://rdmueller.github.io @docToolchain falk.sippach@oio.de @sippsack https://www.jug-da.de/