$30 off During Our Annual Pro Sale. View Details »

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.

Ralf D. Müller

April 26, 2018
Tweet

More Decks by Ralf D. Müller

Other Decks in Programming

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/