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.

Transcript

1. Docs-as-Code Architekturdokumentation leicht gemacht Ralf D. Müller, Falk Sippach @docToolchain
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
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
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
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
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
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
8. 26.04.2018 @RalfDMueller @sippsack @docToolchain 8 Hauptsache, du machst es nicht mit Word!
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
10. Leichtgewichtige Textformate Plain-Text (Markdown, AsciiDoc) LaTex/DocBook Wiki Mindmaps Richtext 26.04.2018 @RalfDMueller @sippsack @docToolchain 10
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, …
12. Dateiablage 26.04.2018 @RalfDMueller @sippsack @docToolchain 12 Foto von UliSchu: https://pixabay.com/en/organization-register-folder-files-1205171/ (CC0 Public Domain Lizenz)
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
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
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
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
17. Die Wahl der Sprache 26.04.2018 @RalfDMueller @sippsack @docToolchain 17 Markdown, textile reStructuredText AsciiDoc(tor)
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
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
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
21. build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/ 26.04.2018 @RalfDMueller @sippsack @docToolchain 21
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
23. Scaffolding 26.04.2018 @RalfDMueller @sippsack @docToolchain 23 Guides
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
25. arc42 – eher Kleiderschrank als Formular 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 25
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
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) ****
28. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html 26.04.2018 @RalfDMueller @sippsack @docToolchain 28
29. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR .adoc 26.04.2018 @RalfDMueller @sippsack @docToolchain 29
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
31. Diagramme 26.04.2018 @RalfDMueller @sippsack @docToolchain 31
32. Diagramme: PlantUML http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ Komplexe Diagramme als einfachen Text verwalten 26.04.2018 @RalfDMueller @sippsack @docToolchain 32
33. Diagramme: PlantUML 26.04.2018 @RalfDMueller @sippsack @docToolchain 33
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
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
36. Diagrams: PlantUML 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 36
37. Diagrams: PlantUML 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 37
38. PlantUML $ java -jar plantuml.jar -metadata activity.png 26.04.2018 @RalfDMueller @sippsack @docToolchain 38 http://mrhaki.blogspot.de/search/label/PlantUML
39. Diagramme: Modellierung 26.04.2018 @RalfDMueller @sippsack @docToolchain 39
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
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
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
43. treat Docs-as-Code IV: automate 26.04.2018 @RalfDMueller @sippsack @docToolchain 43
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
45. Stakeholder 26.04.2018 @RalfDMueller @sippsack @docToolchain 45
46. .docx bzw. MS Word http://pandoc.org 26.04.2018 @RalfDMueller @sippsack @docToolchain 46
47. .docx bzw. MS Word 26.04.2018 @RalfDMueller @sippsack @docToolchain 47 .docx bzw. MS Word oder PDF via PDF-Plugin…
48. Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 48
49. Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 49
50. Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 50
51. Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 51
52. Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 52
53. Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 53
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
55. Managing Tables in AsciiDoc 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 55
56. Testing 26.04.2018 @RalfDMueller @sippsack @docToolchain 56
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
58. Automatisiertes Testing der Doku https://github.com/aim42/htmlSanityCheck 26.04.2018 @RalfDMueller @sippsack @docToolchain 58
59. … demnächst: Linting 26.04.2018 @RalfDMueller @sippsack @docToolchain 59 http://www.hemingwayapp.com/ https://github.com/btford/write-good
60. Bonus: Export PPT ▪Sprechernotizen enthalten asciidoc ▪Slides und asciidoc werden automatisch exportiert 26.04.2018 @RalfDMueller @sippsack @docToolchain 60
61. Bonus: Export PPT 26.04.2018 @RalfDMueller @sippsack @docToolchain 61
62. Ausführbare Dokumentation 26.04.2018 @RalfDMueller @sippsack @docToolchain 62
63. jQAssistant: Regeln in AsciiDoc 26.04.2018 @RalfDMueller @sippsack @docToolchain 63 j
64. Living Documentation 26.04.2018 @RalfDMueller @sippsack @docToolchain 64
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 * ----
66. docToolchain 26.04.2018 @RalfDMueller @sippsack @docToolchain 66
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/