Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz

28.8.2018, Java User Group, Deutsche Nationalbibliothek, Frankfurt

https://sites.google.com/site/jugffm/home/29-08-2018-docs-as-code-arc42-asciidoc-gradle-co-im-einsatz
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

Der Vortrag zeigt, wie Sie die Qualität Ihrer Dokumentation erhöhen und gleichzeitig den Aufwand zur Pflege reduzieren, indem Sie Ihre Dokumentation genauso wie Ihren Code verwalten und in den Build integrieren.

Anhand des Beispiels einer Architekturdokumentation, zeigt Ralf wie Sie mit dem arc42-Template im AsciiDoc-Format und Gradle als Build-Tool einfach Diagramme in Ihre Dokumentation integrieren, Stakeholderspezifische 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

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

August 29, 2018
Tweet

Transcript

  1. Docs-as-Code Docs-as-Code: arc42, AsciiDoc, Gradle & Co. im Einsatz Ralf

    D. Müller @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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 2
  3. Dr. Gernot Starke innoQ Fellow Softwarearchitektur ▪ Entwurf ▪ Evolution

    + Modernisierung ▪ Dokumentation ▪ Reviews +49 177 7282570 gernot.starke@innoq.com
  4. Was machen wir die nächsten 60 Minuten? Mischung aus Tipps

    zu arc42 und docs-like-code Best Practice zum Umgang zur Pflege einer Architekturdokumentation Experimentelle Features :-) Vorschläge aus Erfahrung, keine Silver Bullet 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 4
  5. Das VENOM Projekt VEry NOrMal System Gewachsene Dokumentation Unterschiedliche Stakholder

    Aufgrund verschiedener Änderungen stets im Wandel Hoher Pflegeaufwand 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 5
  6. Darf ich vorstellen? Geoff – Solution Architect Geoff ist Solution

    Architect bei SAMM Inc Zuständig für VENOM Starker technischer Background Aufgaben: Weiterentwicklung der Architektur Pflege der Dokumentation Kommunikation der Architektur 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 6
  7. 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 7

  8. arc42 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 8

  9. Heutiger Fokus: Architektur Docs-as-Code Wie schreibe ich eine System-Dokumentation? 31.05.2018

    @RalfDMueller @arc42Tipps @docToolchain 9 Dr. Peter Hruscka http://www.peterhruschka.eu/ Dr. Gernot Starke http://gernotstarke.de/ http://arc42.org/ DAS Template für die Dokumentation eines Software Systems.
  10. arc42 … 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 10 … ist das

    Standard-Template im deutschsprachigen Raum … ist verfügbar in Deutsch, Englisch und Spanisch … ist verfügbar in > 9 Formaten (.adoc, .docx, .rst, .md, .tex …) … gibt der Dokumentation eine einheitliche Struktur … ist verfügbar mit und ohne Hilfestellung … hilft die richtigen Aspekte richtig zu dokumentieren
  11. arc42 – ein Kleiderschrank für Dokumentation 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain

    11
  12. arc42 – ein Kleiderschrank für Dokumentation 1. Requirements & Goals

    31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 12 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
  13. Format der Dokumentation MS Word ist der etablierte Standard Arc42

    existiert in vielen Formaten: Docx latex html Asciidoc textile confluence markdown Geoff wählt AsciiDoc aufgrund vieler Vorteile 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 13
  14. arc42 Formate AsciiDoc ist aus unserer Sicht das flexibelste Format

    Da es in alle anderen Formate (fast verlustfrei) gewandelt werden kann, gibt es immer „Plan B“ 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 14
  15. Treat Docs-as-Code 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 15

  16. 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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 16
  17. demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3"

    } Demo – eine erste Konvertierung 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 17
  18. 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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 18
  19. build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/

    30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 19
  20. Tools zur Konvertierung Geringste Einstiegshürde: Gradle und asciidoctorj Maven ist

    aufwändiger, gut unterstützt Gradle bezüglich weiterer Build-Steps flexibler
  21. Out-of-the-Box Features „ablenkungsfrei“ – Dokumentation wie eMails schreiben Gliederung in

    Unterdokumente Neugliederung je nach Stakeholder Bilder werden referenziert, nicht eingebettet leichte Versionierung „handle Docs-as-Code“ Formatierung von Source-Code Reviews, Pull-Requests, Versionierung durch Git Konvertierung nach HTML5 und DocBook 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 21
  22. arc42 als AsciiDoc Template 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 23 ==

    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) ****
  23. .adoc .adoc …doch die Reise beginnt erst Geoff ist mit

    seiner Entscheidung erst mal zufrieden die alte Dokumentation muss aber zunächst überführt werden Geoff entscheidet sich im Rahmen einer Überarbeitung die Dokumentation per Copy & Paste in AsciiDoc zu überführen. .docx .adoc .html 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 24
  24. 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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 25
  25. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html 30.08.2018

    @RalfDMueller @arc42Tipps @docToolchain 26
  26. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR

    .adoc 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 27
  27. treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR

    .adoc Build- Server On Change Publish 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 28
  28. Diagramme 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 29

  29. Diagramme 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 30 http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ Komplexe Diagramme

    als einfachen Text verwalten
  30. 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 ---- 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 31
  31. Diagramme: PlantUML 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 32

  32. Diagramme: PlantUML 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 33

  33. PlantUML Nicht alle Diagramm-Typen sind geeignet für PlantUML Sequenzdiagramme sind

    jedoch perfekt! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 34
  34. Asciidoctor Plugins AsciidoctorJ oder jRuby? Verschiedene Output-Formate beachten! 30.08.2018 @RalfDMueller

    @arc42Tipps @docToolchain 35
  35. Diagramme: Nicht malen, modellieren! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 36

  36. Diagramme: Modellierung Geoff pflegt seine Architektur in einem UML- Modellierungstool

    Das Einbetten der Grafiken in die Dokumentation ist jedoch schwerfällig Des weiteren macht Geoff sich auch gerne Notizen im UML-Modell, welche dann in der Dokumentation fehlen 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 37
  37. 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. 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 38
  38. 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. 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 39
  39. === Stakeholder ==== Users and Groups of Users [[figure-users]] image::ea/1.5_Stakeholder.png[title="Users

    and Groups of Users"] [cols="2,3,3,2" options="header"] .Users and Groups of Users |=== | Role | Description | Goal | Comment include::../../ea/stakeholder.ad[] |=== treat Docs-as-Code: automate! 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 40
  40. treat Docs-as-Code IV: automate 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 41

  41. Don‘t know how to draw your component diagrams? => take

    a look at the C4-Model by Simon Brown https://c4model.com/ Context, Containers, Components, Classes 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 42 Diagramme
  42. Stakeholder 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 43

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

  44. .docx bzw. MS Word

  45. ...bzw. pdf

  46. Seitenumbrüche … machen bei single-page HTML keinen Sinn … sind

    aber klasse für PDF und .docx! <<<< Apropos single-page HTML… :data-uri: 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 48
  47. Zusammenarbeit 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 49

  48. Zusammenarbeit Aber alle anderen Dokumente sind in Confluence… Confluence speichert

    die Seiten intern als xhtml …und hat eine REST-API et voilá… 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 50
  49. Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 51

  50. Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 52

  51. Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 53

  52. Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 54

  53. Zusammenarbeit 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 55

  54. Tabellen in AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 56 [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 |=== mit MS Excel!
  55. Managing Tables in AsciiDoc 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 57

  56. Testing 31.05.2018 @RalfDMueller @arc42Tipps @docToolchain 58

  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 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 60
  58. Automatisiertes Testing der Doku https://github.com/aim42/htmlSanityCheck 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 61

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

  60. Bonus: Export PPT ▪Sprechernotizen enthalten asciidoc ▪Slides und asciidoc werden

    automatisch exportiert
  61. Bonus: Export PPT

  62. docToolchain 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 65

  63. Fragen? Antworten! 30.08.2018 @RalfDMueller @arc42Tipps @docToolchain 66 https://doctoolchain.github.io https://doctoolchain.github.io/docToolchain https://jaxenter.de/tag/hhgdc

    https://docs-as-co.de https://arc42.org Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com @docToolchain Ralf.D.Mueller@gmail.com @RalfDMüller https://rdmueller.github.io @docToolchain