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

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