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

JavaLand, Brühl, https://programm.javaland.eu/2019/#/scheduledEvent/569976

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

Transcript

1. arc42, AsciiDoc, Gradle & Co. Im Einsatz DB Systel GmbH | Ralf D. Müller | JavaLand | Brühl | 19.03.2019 Platzhalter für Titelbild – Hier können Sie Bilder aus der Mediathek einfügen! Placeholder for title picture – You can insert here pictures from the Mediathek! Docs-as-Code
2. DB Systel GmbH | Ralf D. Müller | 19.03.2019 2
3. Incomplete or confusing documentation #1 Problem with Open Source DB Systel GmbH | Ralf D. Müller | 19.03.2019 3
4. Ralf D. Müller Software Architect @ DB Systel mit Schwerpunkt Web-Technologien Qualität (Security, Testautomation) Produktivität (Gradle, Groovy, Grails) Prozessoptimierung In der Freizeit Geek, arc42 Contributor & Maintainer von docToolchain DB Systel GmbH | Ralf D. Müller | 19.03.2019 5
5. Dr. Gernot Starke – innoQ Fellow Softwarearchitektur Entwurf Evolution + Modernisierung Dokumentation Reviews +49 177 7282570 gernot.starke@innoq.com DB Systel GmbH | Ralf D. Müller | 19.03.2019 6
6. Was machen wir die nächsten 40 Minuten? Mischung aus Tipps zu arc42 und docs-as-code Best Practice zum Umgang zur Pflege einer Architekturdokumentation Experimentelle Features :-) Vorschläge aus Erfahrung, keine Silver Bullet DB Systel GmbH | Ralf D. Müller | 19.03.2019 7
7. Was ist Docs-as-Code? DB Systel GmbH | Ralf D. Müller |19. März 2019 8 ,--._______,-. ,',' , . ,_`-. / / ,' , _` ``. | ) `-.. (,';'""`/ '"`-._ ` \/ ______ \\ : ,o.-`- ,o. )\` -' `---.)) : , d8b ^-. '| `. ` `. |/ __:_ `. | , ` ` \ | ( ,-.`-. ;' ; ` : ; | | , `. / ; : \ ;-'`:::._,`.__),' : ; / , `- `-- ; | / \ ` , | ( ` : : ,\ | \ `. : : : ,' \ : \ `|-- ` \ ,' ,-' :-.-'; : |`--.______; | : : : / | | | \ | ; ; ; / ; _/--' | -hrr- :`-- / \_:_:_| ,',',' | |___ \ `^._,--' / , , .) `-._,-' ------------------------------------------------ This ASCII pic can be found at https://asciiart.website/index.php?art=animals/dogs
8. VEry NOrMal System Gewachsene Dokumentation Unterschiedliche Stakholder Aufgrund verschiedener Änderungen stets im Wandel Hoher Pflegeaufwand Das VENOM Projekt DB Systel GmbH | Ralf D. Müller | 19.03.2019 9
9. 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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 10
10. DB Systel GmbH | Ralf D. Müller | 19.03.2019 11
11. arc42 DB Systel GmbH | Ralf D. Müller | 19.03.2019 12
12. Heutiger Fokus: Architektur Docs-as-Code Wie schreibe ich eine System-Dokumentation? Dr. Peter Hruschka http://www.peterhruschka.eu/ Dr. Gernot Starke http://gernotstarke.de/ http://arc42.org/ DAS Template für die Dokumentation eines Software Systems. DB Systel GmbH | Ralf D. Müller | 19.03.2019 13
13. arc42 … … ist das Standard-Template im deutschsprachigen Raum … ist verfügbar in Deutsch, Englisch und Spanisch und Russisch … 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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 14
14. arc42 – ein Kleiderschrank für Dokumentation DB Systel GmbH | Ralf D. Müller | 19.03.2019 15
15. arc42 – ein Kleiderschrank für Dokumentation 1. Requirements & Goals 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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 16
16. 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 AsciiDoc DB Systel GmbH | Ralf D. Müller | 19.03.2019 17
17. arc42 als AsciiDoc Template == 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) **** DB Systel GmbH | Ralf D. Müller | 19.03.2019 18
18. arc42 Formate DB Systel GmbH | Ralf D. Müller | 19.03.2019 19 AsciiDoc ist aus unserer Sicht das flexibelste Format Da es in alle anderen Formate (fast verlustfrei) gewandelt werden kann, gibt es immer „Plan B“
19. Treat Docs-as-Code DB Systel GmbH | Ralf D. Müller | 19.03.2019 20
20. 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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 21
21. demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3" } Demo – eine erste Konvertierung DB Systel GmbH | Ralf D. Müller | 19.03.2019 22
22. 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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 23
23. build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/ DB Systel GmbH | Ralf D. Müller | 19.03.2019 24
24. Tools zur Konvertierung DB Systel GmbH | Ralf D. Müller | 19.03.2019 25 Geringste Einstiegshürde: Gradle und asciidoctorj Maven ist aufwändiger, gut unterstützt Gradle bezüglich weiterer Build-Steps flexibler
25. 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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 26
26. .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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 28
27. 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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 29
28. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html DB Systel GmbH | Ralf D. Müller | 19.03.2019 30
29. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR .adoc DB Systel GmbH | Ralf D. Müller | 19.03.2019 31
30. treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR .adoc Build- Server On Change Publish DB Systel GmbH | Ralf D. Müller | 19.03.2019 32
31. The End? DB Systel GmbH | Ralf D. Müller | 19.03.2019 33 Danke für Ihre Aufmerksamkeit! Fragen?
32. Diagramme DB Systel GmbH | Ralf D. Müller | 19.03.2019 34
33. Diagramme http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ Komplexe Diagramme als einfachen Text verwalten DB Systel GmbH | Ralf D. Müller | 19.03.2019 35
34. PlantUML DB Systel GmbH | Ralf D. Müller | 19.03.2019 36
35. 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 ---- DB Systel GmbH | Ralf D. Müller | 19.03.2019 37
36. Diagramme: PlantUML DB Systel GmbH | Ralf D. Müller | 19.03.2019 38
37. Diagramme: PlantUML DB Systel GmbH | Ralf D. Müller | 19.03.2019 39
38. draw.io DB Systel GmbH | Ralf D. Müller |19. März 2019 40 PNG-Diagramm <xml> … </xml> Meta-Daten
39. draw.io DB Systel GmbH | Ralf D. Müller |19. März 2019 41
40. Diagramme: Nicht malen, modellieren! DB Systel GmbH | Ralf D. Müller | 19.03.2019 43
41. 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. DB Systel GmbH | Ralf D. Müller | 19.03.2019 45
42. 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. DB Systel GmbH | Ralf D. Müller | 19.03.2019 46
43. === 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! DB Systel GmbH | Ralf D. Müller | 19.03.2019 47
44. treat Docs-as-Code IV: automate DB Systel GmbH | Ralf D. Müller | 19.03.2019 48
45. 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 Diagramme DB Systel GmbH | Ralf D. Müller | 19.03.2019 49
46. Stakeholder DB Systel GmbH | Ralf D. Müller | 19.03.2019 50
47. 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 DB Systel GmbH | Ralf D. Müller | 19.03.2019 51
48. .docx bzw. MS Word http://pandoc.org DB Systel GmbH | Ralf D. Müller | 19.03.2019 52
49. .docx bzw. MS Word DB Systel GmbH | Ralf D. Müller | 19.03.2019 53
50. ...bzw. pdf DB Systel GmbH | Ralf D. Müller | 19.03.2019 54
51. Modulare Dokumentation DB Systel GmbH | Ralf D. Müller |19. März 2019 55 arc42- master.adoc kapitel1.adoc kapitel2.adoc public class HelloWorld { public static void main (String[] args) { // Ausgabe Hello World! System.out.println("Hello World!"); } } include include include kapitel8.adoc kapitel8.1.adoc include business- master.adoc security- master.adoc
52. Seitenumbrüche DB Systel GmbH | Ralf D. Müller | 19.03.2019 56 … machen bei single-page HTML keinen Sinn … sind aber klasse für PDF und .docx! <<<< Apropos single-page HTML… :data-uri:
53. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | 19.03.2019 57
54. Zusammenarbeit Aber alle anderen Dokumente sind in Confluence… Confluence speichert die Seiten intern als xhtml …und hat eine REST-API et voilá… DB Systel GmbH | Ralf D. Müller | 19.03.2019 58
55. Zusammenarbeit: Confluence DB Systel GmbH | Ralf D. Müller | 19.03.2019 59
56. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | 19.03.2019 60
57. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | 19.03.2019 61
58. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | 19.03.2019 62
59. Zusammenarbeit DB Systel GmbH | Ralf D. Müller | 19.03.2019 63
60. Besser: statische Seiten DB Systel GmbH | Ralf D. Müller |19. März 2019 64
61. Besser: statische Seiten DB Systel GmbH | Ralf D. Müller |19. März 2019 65
62. Besser: statische Seiten - DB Systel GmbH | Ralf D. Müller |19. März 2019 66
63. Besser: statische Seiten - DB Systel GmbH | Ralf D. Müller |19. März 2019 67
64. Zusammenarbeit - Tabellen DB Systel GmbH | Ralf D. Müller |19. März 2019 68
65. Tabellen in AsciiDoc [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! DB Systel GmbH | Ralf D. Müller | 19.03.2019 69
66. Managing Tables in AsciiDoc DB Systel GmbH | Ralf D. Müller | 19.03.2019 70
67. Export PPT Sprechernotizen enthalten asciidoc Slides und asciidoc werden automatisch exportiert DB Systel GmbH | Ralf D. Müller | 19.03.2019 71
68. Export PPT DB Systel GmbH | Ralf D. Müller | 19.03.2019 72
69. Testing DB Systel GmbH | Ralf D. Müller | 19.03.2019 73
70. Broken Links Geoff fällt auf, dass er immer wieder mit Probleme mit Tippfehlern in Dateinamen oder Verlinkungen im Dokument hat Wie löst man solche Probleme mit Code? => natürlich mit automatisierten Tests! DB Systel GmbH | Ralf D. Müller | 19.03.2019 74
71. Automatisiertes Testing der Doku DB Systel GmbH | Ralf D. Müller | 19.03.2019 75 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
72. Automatisiertes Testing der Doku DB Systel GmbH | Ralf D. Müller | 19.03.2019 76 https://github.com/aim42/htmlSanityCheck
73. … demnächst: Linting http://www.hemingwayapp.com/ https://github.com/btford/write-good DB Systel GmbH | Ralf D. Müller | 19.03.2019 77
74. docToolchain DB Systel GmbH | Ralf D. Müller | 19.03.2019 78
75. DB Systel GmbH | Ralf D. Müller | 19.03.2019 79
76. Vielen Dank für Ihre Aufmerksamkeit! https://docs-as-co.de @docToolchain Image-Credits: Title - Photo by Susan Yin on Unsplash Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com www.dbsystel.de