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

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

    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
    | [email protected]
    | 555 102
    | 40388
    | 2
    | Erika Mustermann
    | Scrum Master
    | [email protected]
    | 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 [email protected]
    [email protected]
    @RalfDMueller
    https://rdmueller.github.io
    @docToolchain
    [email protected]
    @sippsack
    https://www.jug-da.de/

    View Slide