Dokumentation am (Riesen-)Beispiel – arc42, AsciiDoc und Co. in Aktion

JAX 2017, von Dr. Gernot Starke und Ralf. D. Müller

Anhand eines großen Systems zeigen Gernot und Ralf, wie Sie mit ziemlich wenig Aufwand angemessene und vernünftige Dokumentation für unterschiedliche Stakeholder produzieren – sodass Entwicklungsteams dabei auch noch Spaß haben.
Unser Rezept: AsciiDoc mit arc42 mischen, Automatisierung mit Gradle und Maven hinzufügen und mit Diagramm- oder Modellierungstools Ihrer Wahl kombinieren. Schon sind schicke HTML- und reviewfähige PDF-Dokumente fertig. Auf Wunsch gibts DOCX und Confluence als Zugabe.
Wir zeigen, wie Sie Doku genau wie Quellcode verwalten können, stakeholderspezifische Dokumente erzeugen und Diagramme automatisiert integrieren können. Einige Teile dieser 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.

Transcript

1. Dokumentation am
   (Riesen-)Beispiel
   arc42, AsciiDoc und Co. in Aktion
   Dr. Gernot Starke & Ralf D. Müller
   

   View Slide

2. Dr. Gernot Starke
   innoQ Fellow
   Softwarearchitektur
   ▪ Entwurf
   ▪ Evolution + Modernisierung
   ▪ Dokumentation
   ▪ Reviews
   +49 177 7282570
   gernot.starke@innoq.com
   

   View Slide

3. Ralf D. Müller
   Bei Tag Solution Architect
   in der Digital Factory
   der Deutschen Bank.
   In der Freizeit Geek:
   ▪ Web-Technologien
   ▪ Qualität (Security, Testautomation)
   ▪ Produktivität (Gradle, Groovy, Grails)
   Maintainer von docToolchain
   

   View Slide

4. Das erwartet Sie !
   ▪praktische Architekturdokumentation
   ▪Tipps zu arc42 und docs-like-code
   ▪Experimentelle Features :-)
   ▪Vorschläge aus Erfahrung
   NSB (No Silver Bullet)
   

   View Slide

5. Das VENOM Projekt
   ▪ VEry NOrMal System
   ▪ Gewachsene Dokumentation
   ▪ Unterschiedliche Stakeholder
   ▪ Aufgrund verschiedener Änderungen
   stets im Wandel
   ▪ Hoher Pflegeaufwand
   

   View Slide

6. Darf ich vorstellen? Geoff – Solution Architect
   ▪Solution Architect für VENOM
   ▪solider technischer Background
   Aufgaben (u.a.):
   ▪Evolution des Systems
   ▪Dokumentation + Kommunikation
   der Architektur
   

   View Slide

7. Format der Dokumentation
   •MS Word: etablierter Standard
   •arc42 in vielen Formaten:
   • docx
   • asciidoc
   • markdown
   • latex
   • html
   • textile
   • confluence
   

   View Slide

8. arc42 Formate
   ▪AsciiDoc aus unserer Sicht flexibelstes Format
   ▪In alle anderen Formate (fast verlustfrei)
   transformierbar, daher immer „Plan B“
   

   View Slide

9. build.gradle demo.adoc console output
   plugins { id "org.asciidoctor.convert" version "1.5.3" }
   Demo – eine erste Konvertierung
   

   View Slide

10. build.gradle demo.adoc console output
    = A first Headline
    And a first paragraph.
    It continuous on the next headline
    Second paragraph.
    == Second-Level Headline
    A link to http://asciidoctor.org/docs[Asciidoctor.org]
    Demo – eine erste Konvertierung
    

    View Slide

11. 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
    

    View Slide

12. build.gradle demo.adoc console output
    Demo – eine erste Konvertierung
    http://asciidoctor.org/docs/render-documents/
    

    View Slide

13. Tools zur Konvertierung
    ▪Geringste Einstiegshürde:
    Gradle und asciidoctorj
    ▪Maven ist aufwändiger, gut unterstützt
    ▪Gradle bezüglich weiterer Build-Steps flexibler
    

    View Slide

14. Out-of-the-Box: docs-as-code
    • „ablenkungsfrei“ –
    Dokumentation wie Code oder eMails schreiben
    • modularisierbar
    • Bilder referenziert, nicht eingebettet
    • Integration von Source-Code
    • Reviews, Pull-Requests, Versionierung durch Git
    • Konvertierung nach HTML5, DocBook u.v.a.
    

    View Slide

15. Unterdokumente
    ▪Setzen von imagedir am Anfang jedes Dokuments:
    ifndef::imagesdir[:imagesdir: ../../images]
    ▪Partielle Includes
    include::subdocument.adoc[tags=xyz]
    ▪Korrektur von Überschriften-Level
    include::subdocument.adoc[tags=xyz, leveloffset=+1]
    

    View Slide

16. .adoc
    .adoc
    …die Reise beginnt erst
    ▪ Geoff bisher zufrieden
    ▪ alte Dokumentation überführen...
    .docx .adoc .html
    

    View Slide

17. treat Docs-as-Code
    ▪ Geoff erkennt, dass die Transformation nach AsciiDoc erst
    der Anfang war
    ▪ Als nächstes möchte er durch den Docs-as-Code Ansatz die
    Überarbeitung der Dokumentation weiter vereinfachen
    

    View Slide

18. treat Docs-as-Code I: Version Control
    .adoc
    .adoc
    .adoc .html
    

    View Slide

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

    View Slide

20. treat Docs-as-Code III: Build-Server
    .adoc
    .adoc
    .adoc .html
    Fork
    PR
    .adoc
    Build-
    Server
    On Change
    Publish
    

    View Slide

21. Diagramme
    • Geoff stört der hohe Pflegeaufwand für Diagramme
    • Beherrscht AsciiDoc nicht PlantUML?
    

    View Slide

22. Diagramme: PlantUML
    

    View Slide

23. Diagramme: PlantUML
    .Benutzer und Benutzergruppen von VENOM
    [plantuml]
    ----
    !pragma graphviz_dot jdot
    :Private User: as private
    :User Groups: as groups
    :Corporate Users: as corporate
    :Government Users: as gov
    :Regulation &\nStandard Bodies: as bodies
    :Operations: as ops
    :internal Users: as internal
    (VENOM\ni.B.O.S.S) as venom
    private -right-> venom
    groups --> venom
    corporate --> venom
    gov -up-> venom
    bodies -up-> venom
    ops --> venom
    internal -left-> venom
    ----
    

    View Slide

24. Diagramme als Plain-Text: PlantUML
    • http://plantuml.com/
    • http://asciidoctor.org/docs/asciidoctor-diagram/
    Nicht alle Diagrammtypen sind für PlantUML gleichgut geeignet.
    Sequenzdiagramme sind jedoch ein sehr guter Anwendungsfall!
    

    View Slide

25. Diagramme
    ▪ Im Zweifel Pfeile immer vom Aufrufenden zum Aufgerufenen
    ▪ Noch keinen eigenen Stil gefunden?
    => C4 von Simon Brown ist ein guter Start
    http://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html
    

    View Slide

26. Diagramme: Modellierung
    ▪Geoff nutzt ein UML-Modellierungstool
    ▪Einbetten der Grafiken schwerfällig
    ▪Notizen im UML-Modell gehen in Doku verloren
    

    View Slide

27. 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.
    

    View Slide

28. 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.
    

    View Slide

29. === 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
    

    View Slide

30. treat Docs-as-Code IV: automate
    

    View Slide

31. Stakeholder
    ▪ Geoff bemerkt schnell, dass nicht jeder mit einer online
    HTML-Dokumentation glücklich ist
    ▪ Er muss für unterschiedliche Stakeholder die Dokumente
    auch unterschiedlich aufbereiten
    

    View Slide

32. .docx bzw. MS Word
    http://pandoc.org
    

    View Slide

33. .docx bzw. MS Word
    

    View Slide

34. ...bzw. pdf
    

    View Slide

35. Überarbeiten in PDF
    ▪ … geht fast besser, als in Word
    

    View Slide

36. Seitenumbrüche
    ▪ …machen keinen Sinn für Single-Page HTML
    ▪ …aber für PDF und .docx!
    ▪ <<<<
    

    View Slide

37. Confluence
    ▪ Aber alle anderen Dokumente sind in Confluence…
    ▪ Confluence speichert die Seiten intern als xhtml
    ▪ …und hat eine REST-API
    ▪ et voilá…
    

    View Slide

38. Zusammenarbeit
    

    View Slide

39. Zusammenarbeit
    

    View Slide

40. Zusammenarbeit
    

    View Slide

41. Zusammenarbeit
    

    View Slide

42. Zusammenarbeit
    

    View Slide

43. Broken Links
    ▪...immer wieder mit Probleme bei
    Dateinamen oder Hyperlinks
    ▪Lösung: automatisierte Tests!
    

    View Slide

44. 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
    

    View Slide

45. Automatisiertes Testing der Doku
    https://github.com/aim42/htmlSanityCheck
    

    View Slide

46. Bonus: Export PPT
    ▪ Sprechernotizen enthalten
    asciidoc
    ▪ Slides und asciidoc werden
    automatisch exportiert
    

    View Slide

47. Bonus: Export PPT
    

    View Slide

48. docToolchain
    

    View Slide

49. Danke!
    Ralf D. Müller
    @RalfDMüller
    https://rdmueller.github.io
    @docToolchain
    Gernot Starke
    @GernotStarke
    http://arc42.org/
    @arc42Tipps
    Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com
    

    View Slide