Hitchhikers Guide to Architecture Documentation

Together with Gernot Starke at Software Architecture Summit 2017 in Berlin:

Use AsciiDoctor and simple automation to treat your (architecture) documentation like source code - close to your IDE, ideally suited for practical developers

Transcript

1. Hitchhikers Guide to Architecture Documentation arc42, AsciiDoc und Co. in Aktion Ralf D. Müller & Gernot Starke
2. 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
3. Dr. Gernot Starke innoQ Fellow Softwarearchitektur § Entwurf § Evolution + Modernisierung § Dokumentation § Reviews +49 177 7282570 gernot.starke@innoq.com
4. Das erwartet Sie ! §praktische Architekturdokumentation §Tipps zu arc42 und docs-like-code §Experimentelle Features :-) §Vorschläge aus Erfahrung NSB (No Silver Bullet)
5. „Schrank“ für Architektur-Info Anforderungen Entscheidungen Strukturen von Sourcecode
6. Beispiel (CRM-System, 2000+ PT)
7. Beispiel (Datenmigration, 4000+ PT)
8. Tabellen Text Diagramme Verzeichnisse
9. Stakeholder von Doku Breites Spektrum... Management, Auftraggeber, Projekt-Steuerkreis, sonstige Projekt-Gremien, PMO, Product- Owner, Projektmanager, Produktmanager, Fachbereich, Unternehmens-/Enterprise- Architekt, Architektur-Abteilung, Methoden-Abteilung, QS-Abteilung, IT-Strategie, Softwarearchitekten, Software-Designer, Entwicklungsteam, Tester, Konfigurationsmanager, Build-Manager, Release-Manager, Wartungsteam, externe Dienstleister, Zulieferer, Hardware-Designer, Rollout-Manager, Infrastruktur-Planer, Security, Behörde, Aufsichtsgremium, Auditor, Mitbewerber/Konkurrent, Endanwender, Fachpresse, Fachadministrator, Systemadministrator, Ops-Team, Operator, Hotline, Betriebsrat, Lieferant von Standardsoftware, verbundene Projekte, API-Nutzer, Normierungsgremium, Gesetzgeber...
10. VENOM System
11. VENOM § VEry NOrMal System § Gewachsenes System § Unterschiedliche Stakeholder § Hoher Pflegeaufwand
12. Geoff – Solution Architect §... für VENOM §solider technischer Background Aufgaben (u.a.): §Evolution des Systems §Dokumentation + Kommunikation der Architektur
13. Methodik- Modularisiere Dokumentation großer Systeme! Eigene Dokumente für relevante Teilsysteme Siehe: http://faq.arc42.org/questions/J-1/ VENOM Architecture 1. Einführung und Ziele 3. Kontextabgrenzung 5. Bausteinsicht 8. Konzepte 4. Lösungsstrategie 12. Glossar 11. Risiken & techn. Schulden VENOM-Commons 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Konzepte 10. Qualitätsszenarien 9. Entwurfsentscheidungen 4. Lösungsstrategie 12. Glossar VENOM-NGO 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht Private-Customer… 8. Konzepte 9. Entwurfsentscheidungen 4. Lösungsstrategie Ziele des Gesamtsystems Wesentliche Qualitätsanforderungen strategische Entscheidungen Bausteinsicht Level-1 zentrale Konzepte Übergreifend genutzte Begriffe Verweise Verweise Verweise …
14. Methodik- Trenne Projekt- von Systemdokumentation! Projektdokumentation ~arc42 „locker“ Diskussionen Implementation-Guide, Tasks / Issues Systemdokumentation Weitere relevante Infos... (Betrieb/Admin, Test, Release...) 11. Risiken ARC42 Architektur-Dokumentation 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Konzepte 10. Qualitätsszenarien 9. Entwurfsentscheidungen 4. Lösungsstrategie 12. Glossar Team „Gärtner“
15. Methodik- Dokumentiere sparsam! Siehe: http://docs.arc42.org/keywords/#lean •Tip 3-5: Restrict the context to an overview, avoid too many details! •Tip 3-6: Simplify the context by categorization! •Tip 4-1: Explain the solution strategy as compact as possible (e.g. as list of keywords)! •Tip 4-2: Describe the solution approaches as a table! •Tip 4-5: Let the solution strategy grow iteratively / incrementally! •Tip 5-3: Always describe level-1 of the building block view ('Level-1 is your friend')! •Tip 5-6: Hide the inner workings of blackboxes! •Tip 6-2: Document only a few runtime scenarios! •Tip 6-3: Document 'schematic' (instead of detailed) scenarios! •Tip 6-9: Use a textual notation to describe runtime scenarios! •Tip 7-7: Use tables to document software/hardware mapping!! •Tip 8-1: Explain the Concepts! •Tip 8-9: Document decisions instead of concepts! •Tip 9-1: Document only architecturally relevant decisions! •Tip 9-7: Document decisions informally as a blog (RSS-feed)! •Tip 12-2: Document the glossary as a table! •Tip 12-5: Keep the glossary compact! Avoid trivia. •Tip 12-6: Make your 'product owner' or 'project manager' responsible for the glossary •Tip 1-16: Describe only the top 3-5 quality goals in the introduction! •Tip 1-22: Skip the stakeholder table if your management already maintains it! •Tip 1-23: Classify your stakeholders by interest and influence! •Tip 3-17: Combine business context with technical information! •Tip 3-19: Defer technical context to the deployment view! •Tip 5-10: Use crosscutting concepts to describe or specify similarities in building blocks! •Tip 5-15: Align the mapping of source-code to building-blocks along the directory and file structure! •Tip 6-10: Use both small and large building blocks in scenarios! •Tip 7-10: Leave hardware decisions to hardware-experts! •Tip 8-10: Use the collection from arc42 as checklist for concepts! •Tip 5-21: Describe or specify internal interfaces with minimal effort!
16. Teil 2: Docs-as-Code
17. Format der Dokumentation (1) • MS Word: etablierter Standard • aber: • Diagramme? • Quellcode integrieren? • Teamarbeit? • Versionierung? • diff/merge? • Geek-Akzeptanz? • Build-Integration?
18. §Dokumentation wie Code (Plain-Text) • Diagramme! • Quellcode integrieren! • Teamarbeit! • Versionierung! • diff/merge! • Geek-Akzeptanz! • Build-Integration!
19. arc42 Formate §AsciiDoc: flexibelstes Format (unserer Meinung nach) §In viele andere Formate transformierbar (fast immer verlustfrei)
20. Demo 01-SimpleBuild git clone git@bitbucket.org:arcSummit2017/examples.git
21. Demo 01-SimpleBuild
22. 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
23. build.gradle demo.adoc console output plugins { id "org.asciidoctor.convert" version "1.5.3" } Demo – eine erste Konvertierung
24. 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
25. build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/
26. Tools zur Konvertierung §Geringste Einstiegshürde: Gradle und asciidoctorj §Maven ist aufwändiger, gut unterstützt §Gradle bezüglich weiterer Build-Steps flexibler 01-SimbleBuild
27. 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.
28. .adoc .adoc …die Reise beginnt erst § Geoff bisher zufrieden § alte Dokumentation überführen... .docx .adoc .html
29. 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. treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html
31. treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR .adoc
32. treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR .adoc Build- Server On Change Publish
33. Teil 3: AsciiDoc 101
34. AsciiDoc 101 Tabellen Text Diagramme Verzeichnisse, Nummerierung Headings Verweise Fußnoten Kästen Sourcecode
35. Cheatsheet: http://powerman.name/doc/asciidoc
36. Ascii{Doctor|Doc}? • AsciiDoc: • Format (Syntax) einer Sprache zum Erstellen von Dokumenten • Python-basierter „Übersetzer“ • OpenSource-Projekt seit 2002, letzte Version von 2013 • AsciiDoctor • Ruby-basierter (schneller!) Übersetzer von AsciiDoc-Dokumenten • (nahezu) vollständig kompatibel zu AsciiDoc • Aber: Transformation in definierten Phasen, d.h. programmatischen Einfluss auf Übersetzung • enthält (wenige) Erweiterungen gegenüber AsciiDoc
37. Text – bei Bedarf auch schön... forced + line break forced line break normal, _italic_, *bold*, +mono+. ``double quoted'', `single quoted'. normal, ^super^, ~sub~. normal, italic, bold, mono. “double quoted”, ‘single quoted’. normal, super, sub . Command: `ls -al` + mono *bold*+ `passthru *bold*` Command: ls -al mono bold passthru *bold* Path: '/some/filez.txt', '.b' Path: /some/filez.txt, .b [red]#red text# [yellow-background]#on yellow# [big]#large# [red yellow-background big]*all bold* red text on yellow large all bold
38. Headings – Struktur in Dokumenten (1) == Level 1 Text. === Level 2 Text. ==== Level 3 Text. ===== Level 4 Text. Level 1 Text. Level 2 Text. Level 3 Text. Level 4 Text.
39. Headings (2) Präambel • Pfade • i18n Einstellungen
40. Diagramme & Bilder (1) === Business Context image::hsc-context.png[title="Business Context"]
41. Diagramme & Bilder (1b) === Business Context .Business Context image::hsc-context.png[]
42. Diagramme (2) === Images image::plain.png[] image::withCaption.png[title=“Bild-Unterschrift"] .Bild-Unterschrift image::someImage.png[] image::full.png[„alt“,title=“caption"]
43. Diagramme (3) :imagesdir: ../images image::plain.png[] Pfad relativ zu „imagesDir“ Default-Pfad für Bilder
44. Diagramme (4): Größe image::sized.png[„alt“, 600, 400] Breite (width) Höhe (height) image::sized.png[„alt“, width=600, height=400]
45. Verweise (1) Dokument-intern • Verweise auf Überschriften • Verweise auf beliebige Textpassagen (z.B. Glossareintrag) • Literaturverweise • Verweise aus HTML ImageMaps Externe Links
46. Siehe <<Kontextabgrenzung>>. [[Kontextabgrenzung]] === Kontextabgrenzung image::context.png[] Verweise (2) der Verweis... Sprungziel („target“, ID)
47. Siehe <<kontextabgrenzung>>. === Kontextabgrenzung image::context.png[] Verweise (3) „DRY“ Default-ID: Aus Heading generiert
48. Siehe <<context>>. [[context, Kontext]] === Kontextabgrenzung image::context.png[] Verweise (4) der Verweis... Sprungziel („target“, mit Symbol und Name)
49. Tabellen in arc42 für: • Stakeholder • Qualitätsanforderungen / -szenarien • externe Schnittstellen • Whitebox-Template • Risiken • Glossar
50. Tabellen (1) |=== |column 1, row 1 |column 2, row 1 |column 3, row 1 |column 1, row 2 |column 2, row 2 |column 3, row 2 |===
51. Tabellen mit Header [cols=3,options="header"] |=== |Header-1 | Header-2 | Header-3 |c1r1 |c2r1 |c3r1 |c1r2 |c2r2 |c3r2 |=== Layout über Optionen steuern: • Anzahl Spalten • Header/Footer • (relative) Spaltenbreite • links-/rechtsbündig, zentriert
52. Tabellen mit Spaltenbreiten [cols="1,2,4"] |=== |Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1 |Cell in column 1, row 2 |Cell in column 2, row 2 |Cell in column 3, row 2 |=== relative (!) Breite
53. Sourcecode
54. Kästen („admonitions“)
55. Kästen („admonitions“)
56. Editoren für AsciiDoc •(plaintext) Editor • Atom, brackets.io, Sublime, VS-Code, vi & Co. •Editor der IDE • IntelliJ, Eclipse •spezielle AsciiDoc-Tools • AsciiDocFX • AsciiDocLive (https://asciidoclive.com) • Live-Reload Browser Extensions
57. Atom • Syntax Highlighting • Preview • (Autocompletion)
58. IntelliJ • Syntax Highlighting • Preview
59. IntelliJ (2) • versteht geschachtelte Includes
60. AsciiDocLive • Syntax Highlighting • Preview • Browser-basiert • Lokal installierbar
61. AsciiDocFX • Syntax Highlighting • Preview • diverse Erweiterungen (Formeln, Diagramme etc) • JavaFX basiert • Mac, Win, Linux
62. AsciiDocFX • versteht (geschachtelte) includes...
63. 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]
64. Teil 4: Modulare Doku
65. Modulare Doku... Einstieg Doku-Teile include
66. Dateien einfügen.. == Hier ein Text... include::part1.adoc[] File: master.adoc Dies ist Teil 1. File: part1.adoc
67. Demo 02-Modules git clone git@bitbucket.org:arcSummit2017/examples.git
68. VENOM Dokumente... Architekturdoku Doku des Unternehmens + der IT-Prozesse
69. Modularisierung in VENOM (2) Master-Dokumente
70. Anforderungen Entscheidungen Strukturen von Sourcecode
71. Modularer Aufbau arc42, Version 7.0, Stand März 2017. © Dr. Peter Hruschka und Dr. Gernot Starke. Frei für kommerzielle und private Nutzung. 1. Einführung und Ziele 1.1 Aufgabenstellung 1.2 Qualitätsziele 1.3 Stakeholder 7.Verteilungssicht 7.1 Infrastruktur Ebene 1 7.2 Infrastruktur Ebene 2 …. 2. Randbedingungen 2.1 Technische Randbedingungen 2.2 Organisatorische Randbedingungen 2.3 Konventionen 3. Kontextabgrenzung 3.1 Fachlicher Kontext 3.2 Technischer- oder Verteilungskontext 4. Lösungsstrategie 5. Bausteinsicht 5.1 Ebene 1 5.2 Ebene 2 …. 6. Laufzeitsicht 6.1 Laufzeitszenario 1 6.2 Laufzeitszenario 2 …. 8. Querschnittliche Konzepte 8.1 Fachliche Struktur und Modelle 8.2 Architektur- und Entwurfsmuster 8.3 Unter-der-Haube 8.4 User Experience …. 9. Entwurfsentscheidungen 9.1 Entwurfsentscheidung 1 9.2 Entwurfsentscheidung 2 …. 10. Qualitätsanforderungen 10.1 Qualitätsbaum 10.2 Qualitätsszenarien 11. Risiken und technische Schulden 12. Glossar
72. Demo 03-arc42 git clone git@bitbucket.org:arcSummit2017/examples.git
73. Demo 03-arc42
74. Weitere Infos + Beispiele https://leanpub.com/arc42byexample/c/arc42-sagt-danke-2017
75. Dateien einfügen (ein Problem).. == Bar-API include::real.adoc[] File: bar.adoc == Real-Info You need to know... File: real.adoc ==== Foo-API Doc include::real.adoc[] File: foo.adoc ??
76. Korrektur von Header-Levels include::part1.adoc[leveloffset=+1]
77. Modular++: Partielles Einfügen
78. Spezialitäten bei Includes... §Partielle Includes für Quellcode include::FooBarApi.java[tags=xyz] §Korrektur von Überschriften-Level include::subdocument.adoc[tags=xyz, leveloffset=+1]
79. Teil 5: Diagramme
80. Diagramme • Geoff stört der hohe Pflegeaufwand für Diagramme • Beherrscht AsciiDoc nicht PlantUML?
81. Diagramme: PlantUML
82. Demo 04-PlantUML git clone git@bitbucket.org:arcSummit2017/examples.git
83. Demo 04-PlantUML
84. 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 ----
85. 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!
86. Asciidoctor Plugins § AsciidoctorJ oder jRuby? § Bei PlantUML Verschiedene Output-Formate beachten!
87. Diagramme § In welche Richtung zeigen die Pfeile im Diagramm? § Datenfluss? § Aktivierung? § Abhängigkeit? § => Im Zweifel Pfeile immer vom Aufrufenden zum Aufgerufenen … und in der Legende erklären § Noch keinen eigenen Stil gefunden? => C4 von Simon Brown ist ein guter Start http://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html
88. Diagramme: Modellierung §Geoff nutzt ein UML-Modellierungstool §Einbetten der Grafiken schwerfällig §Notizen im UML-Modell gehen in Doku verloren
89. 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.
90. 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.
91. === 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
92. treat Docs-as-Code IV: automate
93. Demo 05-EnterpriseArchitect git clone git@bitbucket.org:arcSummit2017/examples.git
94. Demo 05-EnterpriseArchitect
95. Teil 6: Stakeholder
96. 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
97. .docx bzw. MS Word http://pandoc.org
98. .docx bzw. MS Word
99. Export PPT Aufgabe: Powerpoint in Doku integrieren: § Sprechernotizen enthalten asciidoc § Slides und asciidoc werden automatisch exportiert
100. Export PPT
101. Demo 08-PPTX git clone git@bitbucket.org:arcSummit2017/examples.git
102. Demo 08-PPTX
103. ...bzw. pdf
104. Überarbeiten in PDF § … geht fast besser, als in Word
105. Demo 07-PDF git clone git@bitbucket.org:arcSummit2017/examples.git
106. Demo 07-PDF
107. PDF-Header
108. PDF-Header
109. PDF-Header
110. PDF-Header header: height: 0.75in line_height: 1 recto_content: right: 'image:logo.jpg[width="30"]' center: 'VENOM: {document-subtitle}' verso_content: left: 'image:logo.jpg[width="30"]' center: 'VENOM: {document-subtitle}' custom-theme.yml
111. PDF-Header
112. PDF-Header
113. Seitenumbrüche § …machen keinen Sinn für Single-Page HTML § …aber für PDF! § <<<<
114. Confluence § Aber alle anderen Dokumente sind in Confluence… § Confluence speichert die Seiten intern als xhtml § …und hat eine REST-API § et voilá…
115. Zusammenarbeit
116. Zusammenarbeit
117. Zusammenarbeit
118. Zusammenarbeit
119. Zusammenarbeit
120. Zusammenarbeit
121. Changelog 10-Changelog git clone git@bitbucket.org:arcSummit2017/examples.git
122. Changelog 09-Changelog
123. Teil 7: Test der Doku
124. Broken Links §...immer wieder mit Probleme bei Dateinamen oder Hyperlinks §Lösung: automatisierte Tests! §Inhaltliche Fehler (praktisch) nicht testbar...
125. Mögliche (Verweis-)Fehler bei Doku §Broken Cross References (aka Broken Links) §Missing Images §Missing Resources §Multiple Definitions of link targets (ID‘s) §Missing Alt-tags in Images https://github.com/aim42/htmlSanityCheck
126. Ziel: (Unit-)Test https://github.com/aim42/htmlSanityCheck
127. htmlSanityCheck
128. Demo 11-htmlSanityCheck git clone git@bitbucket.org:arcSummit2017/examples.git
129. Demo 11-htmlSanityCheck
130. Kann noch mehr getestet werden?
131. Demo 12-AutomatedTests git clone git@bitbucket.org:arcSummit2017/examples.git
132. Bonus 1: Tabellen mit Excel 13-Excel git clone git@bitbucket.org:arcSummit2017/examples.git
133. Bonus 1: Tabellen mit Excel 13-Excel
134. Bonus 2: HTML Präsentationen mit reveal.js 14-reveal.js git clone git@bitbucket.org:arcSummit2017/examples.git
135. Bonus 2: HTML Präsentationen mit reveal.js 14-reveal.js
136. docToolchain
137. 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