Hitchhikers Guide to Architecture Documentation arc42, AsciiDoc und Co. in Aktion Ralf D. Müller & Gernot Starke

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

Dr. Gernot Starke innoQ Fellow Softwarearchitektur § Entwurf § Evolution + Modernisierung § Dokumentation § Reviews +49 177 7282570 [email protected]

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

„Schrank“ für Architektur-Info Anforderungen Entscheidungen Strukturen von Sourcecode

Beispiel (CRM-System, 2000+ PT)

Beispiel (Datenmigration, 4000+ PT)

Tabellen Text Diagramme Verzeichnisse

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

VENOM System

VENOM § VEry NOrMal System § Gewachsenes System § Unterschiedliche Stakeholder § Hoher Pflegeaufwand

Geoff – Solution Architect §... für VENOM §solider technischer Background Aufgaben (u.a.): §Evolution des Systems §Dokumentation + Kommunikation der Architektur

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 …

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“

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!

Teil 2: Docs-as-Code

Format der Dokumentation (1) • MS Word: etablierter Standard • aber: • Diagramme? • Quellcode integrieren? • Teamarbeit? • Versionierung? • diff/merge? • Geek-Akzeptanz? • Build-Integration?

§Dokumentation wie Code (Plain-Text) • Diagramme! • Quellcode integrieren! • Teamarbeit! • Versionierung! • diff/merge! • Geek-Akzeptanz! • Build-Integration!

arc42 Formate §AsciiDoc: flexibelstes Format (unserer Meinung nach) §In viele andere Formate transformierbar (fast immer verlustfrei)

Demo 01-SimpleBuild git clone [email protected]:arcSummit2017/examples.git

Demo 01-SimpleBuild

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

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

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

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

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

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.

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

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

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

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

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

Teil 3: AsciiDoc 101

AsciiDoc 101 Tabellen Text Diagramme Verzeichnisse, Nummerierung Headings Verweise Fußnoten Kästen Sourcecode

Cheatsheet: http://powerman.name/doc/asciidoc

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

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

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.

Headings (2) Präambel • Pfade • i18n Einstellungen

Diagramme & Bilder (1) === Business Context image::hsc-context.png[title="Business Context"]

Diagramme & Bilder (1b) === Business Context .Business Context image::hsc-context.png[]

Diagramme (2) === Images image::plain.png[] image::withCaption.png[title=“Bild-Unterschrift"] .Bild-Unterschrift image::someImage.png[] image::full.png[„alt“,title=“caption"]

Diagramme (3) :imagesdir: ../images image::plain.png[] Pfad relativ zu „imagesDir“ Default-Pfad für Bilder

Diagramme (4): Größe image::sized.png[„alt“, 600, 400] Breite (width) Höhe (height) image::sized.png[„alt“, width=600, height=400]

Verweise (1) Dokument-intern • Verweise auf Überschriften • Verweise auf beliebige Textpassagen (z.B. Glossareintrag) • Literaturverweise • Verweise aus HTML ImageMaps Externe Links

Siehe <>. [[Kontextabgrenzung]] === Kontextabgrenzung image::context.png[] Verweise (2) der Verweis... Sprungziel („target“, ID)

Siehe <>. === Kontextabgrenzung image::context.png[] Verweise (3) „DRY“ Default-ID: Aus Heading generiert

Siehe <>. [[context, Kontext]] === Kontextabgrenzung image::context.png[] Verweise (4) der Verweis... Sprungziel („target“, mit Symbol und Name)

Tabellen in arc42 für: • Stakeholder • Qualitätsanforderungen / -szenarien • externe Schnittstellen • Whitebox-Template • Risiken • Glossar

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

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

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

Sourcecode

Kästen („admonitions“)

Kästen („admonitions“)

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

Atom • Syntax Highlighting • Preview • (Autocompletion)

IntelliJ • Syntax Highlighting • Preview

IntelliJ (2) • versteht geschachtelte Includes

AsciiDocLive • Syntax Highlighting • Preview • Browser-basiert • Lokal installierbar

AsciiDocFX • Syntax Highlighting • Preview • diverse Erweiterungen (Formeln, Diagramme etc) • JavaFX basiert • Mac, Win, Linux

AsciiDocFX • versteht (geschachtelte) includes...

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]

Teil 4: Modulare Doku

Modulare Doku... Einstieg Doku-Teile include

Dateien einfügen.. == Hier ein Text... include::part1.adoc[] File: master.adoc Dies ist Teil 1. File: part1.adoc

Demo 02-Modules git clone [email protected]:arcSummit2017/examples.git

VENOM Dokumente... Architekturdoku Doku des Unternehmens + der IT-Prozesse

Modularisierung in VENOM (2) Master-Dokumente

Anforderungen Entscheidungen Strukturen von Sourcecode

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

Demo 03-arc42 git clone [email protected]:arcSummit2017/examples.git

Demo 03-arc42

Weitere Infos + Beispiele https://leanpub.com/arc42byexample/c/arc42-sagt-danke-2017

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 ??

Korrektur von Header-Levels include::part1.adoc[leveloffset=+1]

Modular++: Partielles Einfügen

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]

Teil 5: Diagramme

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

Diagramme: PlantUML

Demo 04-PlantUML git clone [email protected]:arcSummit2017/examples.git

Demo 04-PlantUML

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

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!

Asciidoctor Plugins § AsciidoctorJ oder jRuby? § Bei PlantUML Verschiedene Output-Formate beachten!

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

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

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.

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.

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

treat Docs-as-Code IV: automate

Demo 05-EnterpriseArchitect git clone [email protected]:arcSummit2017/examples.git

Demo 05-EnterpriseArchitect

Teil 6: Stakeholder

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

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

.docx bzw. MS Word

Export PPT Aufgabe: Powerpoint in Doku integrieren: § Sprechernotizen enthalten asciidoc § Slides und asciidoc werden automatisch exportiert

Export PPT

Demo 08-PPTX git clone [email protected]:arcSummit2017/examples.git

Demo 08-PPTX

...bzw. pdf

Überarbeiten in PDF § … geht fast besser, als in Word

Demo 07-PDF git clone [email protected]:arcSummit2017/examples.git

Demo 07-PDF

PDF-Header

PDF-Header

PDF-Header

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

PDF-Header

PDF-Header

Seitenumbrüche § …machen keinen Sinn für Single-Page HTML § …aber für PDF! § <<<<

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

Zusammenarbeit

Zusammenarbeit

Zusammenarbeit

Zusammenarbeit

Zusammenarbeit

Zusammenarbeit

Changelog 10-Changelog git clone [email protected]:arcSummit2017/examples.git

Changelog 09-Changelog

Teil 7: Test der Doku

Broken Links §...immer wieder mit Probleme bei Dateinamen oder Hyperlinks §Lösung: automatisierte Tests! §Inhaltliche Fehler (praktisch) nicht testbar...

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

Ziel: (Unit-)Test https://github.com/aim42/htmlSanityCheck

htmlSanityCheck

Demo 11-htmlSanityCheck git clone [email protected]:arcSummit2017/examples.git

Demo 11-htmlSanityCheck

Kann noch mehr getestet werden?

Demo 12-AutomatedTests git clone [email protected]:arcSummit2017/examples.git

Bonus 1: Tabellen mit Excel 13-Excel git clone [email protected]:arcSummit2017/examples.git

Bonus 1: Tabellen mit Excel 13-Excel

Bonus 2: HTML Präsentationen mit reveal.js 14-reveal.js git clone [email protected]:arcSummit2017/examples.git

Bonus 2: HTML Präsentationen mit reveal.js 14-reveal.js

docToolchain

Danke! Ralf D. Müller @RalfDMüller https://rdmueller.github.io @docToolchain Gernot Starke @GernotStarke http://arc42.org/ @arc42Tipps Clipart: presentermedia.com, licenced to [email protected]