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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

8. 26.04.2018 @RalfDMueller @sippsack @docToolchain 8
   Hauptsache,
   du machst es
   nicht mit Word!
   

   View Slide

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
   

   View Slide

10. Leichtgewichtige Textformate
    Plain-Text (Markdown, AsciiDoc)
    LaTex/DocBook
    Wiki
    Mindmaps
    Richtext
    26.04.2018 @RalfDMueller @sippsack @docToolchain 10
    

    View Slide

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, …
    

    View Slide

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)
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

17. Die Wahl der Sprache
    26.04.2018 @RalfDMueller @sippsack @docToolchain 17
    Markdown, textile
    reStructuredText
    AsciiDoc(tor)
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

21. build.gradle demo.adoc console output
    Demo – eine erste Konvertierung
    http://asciidoctor.org/docs/render-documents/
    26.04.2018 @RalfDMueller @sippsack @docToolchain 21
    

    View Slide

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
    

    View Slide

23. Scaffolding
    26.04.2018 @RalfDMueller @sippsack @docToolchain 23
    Guides
    

    View Slide

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
    

    View Slide

25. arc42 – eher Kleiderschrank als Formular
    17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 25
    

    View Slide

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
    

    View Slide

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)
    ****
    

    View Slide

28. treat Docs-as-Code I: Version Control
    .adoc
    .adoc
    .adoc .html
    26.04.2018 @RalfDMueller @sippsack @docToolchain 28
    

    View Slide

29. treat Docs-as-Code II: Git-Flow
    .adoc
    .adoc
    .adoc .html
    Fork
    PR
    .adoc
    26.04.2018 @RalfDMueller @sippsack @docToolchain 29
    

    View Slide

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
    

    View Slide

31. Diagramme
    26.04.2018 @RalfDMueller @sippsack @docToolchain 31
    

    View Slide

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
    

    View Slide

33. Diagramme: PlantUML
    26.04.2018 @RalfDMueller @sippsack @docToolchain 33
    

    View Slide

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
    

    View Slide

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
    

    View Slide

36. Diagrams: PlantUML
    17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 36
    

    View Slide

37. Diagrams: PlantUML
    17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 37
    

    View Slide

38. PlantUML
    $ java -jar plantuml.jar -metadata activity.png
    26.04.2018 @RalfDMueller @sippsack @docToolchain 38
    http://mrhaki.blogspot.de/search/label/PlantUML
    

    View Slide

39. Diagramme: Modellierung
    26.04.2018 @RalfDMueller @sippsack @docToolchain 39
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

43. treat Docs-as-Code IV: automate
    26.04.2018 @RalfDMueller @sippsack @docToolchain 43
    

    View Slide

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
    

    View Slide

45. Stakeholder
    26.04.2018 @RalfDMueller @sippsack @docToolchain 45
    

    View Slide

46. .docx bzw. MS Word
    http://pandoc.org
    26.04.2018 @RalfDMueller @sippsack @docToolchain 46
    

    View Slide

47. .docx bzw. MS Word
    26.04.2018 @RalfDMueller @sippsack @docToolchain 47
    .docx bzw. MS Word oder PDF
    via PDF-Plugin…
    

    View Slide

48. Zusammenarbeit
    26.04.2018 @RalfDMueller @sippsack @docToolchain 48
    

    View Slide

49. Zusammenarbeit
    26.04.2018 @RalfDMueller @sippsack @docToolchain 49
    

    View Slide

50. Zusammenarbeit
    26.04.2018 @RalfDMueller @sippsack @docToolchain 50
    

    View Slide

51. Zusammenarbeit
    26.04.2018 @RalfDMueller @sippsack @docToolchain 51
    

    View Slide

52. Zusammenarbeit
    26.04.2018 @RalfDMueller @sippsack @docToolchain 52
    

    View Slide

53. Zusammenarbeit
    26.04.2018 @RalfDMueller @sippsack @docToolchain 53
    

    View Slide

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
    

    View Slide

55. Managing Tables in AsciiDoc
    17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 55
    

    View Slide

56. Testing
    26.04.2018 @RalfDMueller @sippsack @docToolchain 56
    

    View Slide

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
    

    View Slide

58. Automatisiertes Testing der Doku
    https://github.com/aim42/htmlSanityCheck
    26.04.2018 @RalfDMueller @sippsack @docToolchain 58
    

    View Slide

59. … demnächst: Linting
    26.04.2018 @RalfDMueller @sippsack @docToolchain 59
    http://www.hemingwayapp.com/
    https://github.com/btford/write-good
    

    View Slide

60. Bonus: Export PPT
    ▪Sprechernotizen enthalten
    asciidoc
    ▪Slides und asciidoc werden
    automatisch exportiert
    26.04.2018 @RalfDMueller @sippsack @docToolchain 60
    

    View Slide

61. Bonus: Export PPT
    26.04.2018 @RalfDMueller @sippsack @docToolchain 61
    

    View Slide

62. Ausführbare Dokumentation
    26.04.2018 @RalfDMueller @sippsack @docToolchain 62
    

    View Slide

63. jQAssistant: Regeln in AsciiDoc
    26.04.2018 @RalfDMueller @sippsack @docToolchain 63
    j
    

    View Slide

64. Living Documentation
    26.04.2018 @RalfDMueller @sippsack @docToolchain 64
    

    View Slide

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
    *
    ----
    

    View Slide

66. docToolchain
    26.04.2018 @RalfDMueller @sippsack @docToolchain 66
    

    View Slide

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/
    

    View Slide