Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Hitchhikers Guide to Architecture Documentation

Hitchhikers Guide to Architecture Documentation

Together with Ralf D. Müller:

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

Dr. Gernot Starke

September 18, 2017
Tweet

More Decks by Dr. Gernot Starke

Other Decks in Programming

Transcript

  1. 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
  2. Dr. Gernot Starke innoQ Fellow Softwarearchitektur § Entwurf § Evolution

    + Modernisierung § Dokumentation § Reviews +49 177 7282570 [email protected]
  3. Das erwartet Sie ! §praktische Architekturdokumentation §Tipps zu arc42 und

    docs-like-code §Experimentelle Features :-) §Vorschläge aus Erfahrung NSB (No Silver Bullet)
  4. 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...
  5. Geoff – Solution Architect §... für VENOM §solider technischer Background

    Aufgaben (u.a.): §Evolution des Systems §Dokumentation + Kommunikation der Architektur
  6. 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 …
  7. 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“
  8. 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!
  9. Format der Dokumentation (1) • MS Word: etablierter Standard •

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

    Teamarbeit! • Versionierung! • diff/merge! • Geek-Akzeptanz! • Build-Integration!
  11. arc42 Formate §AsciiDoc: flexibelstes Format (unserer Meinung nach) §In viele

    andere Formate transformierbar (fast immer verlustfrei)
  12. 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
  13. 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
  14. 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
  15. 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.
  16. .adoc .adoc …die Reise beginnt erst § Geoff bisher zufrieden

    § alte Dokumentation überführen... .docx .adoc .html
  17. 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
  18. 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
  19. 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
  20. 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.
  21. Verweise (1) Dokument-intern • Verweise auf Überschriften • Verweise auf

    beliebige Textpassagen (z.B. Glossareintrag) • Literaturverweise • Verweise aus HTML ImageMaps Externe Links
  22. Tabellen in arc42 für: • Stakeholder • Qualitätsanforderungen / -szenarien

    • externe Schnittstellen • Whitebox-Template • Risiken • Glossar
  23. 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 |===
  24. 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
  25. 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
  26. 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
  27. AsciiDocFX • Syntax Highlighting • Preview • diverse Erweiterungen (Formeln,

    Diagramme etc) • JavaFX basiert • Mac, Win, Linux
  28. 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]
  29. 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
  30. 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 ??
  31. 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 ----
  32. 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!
  33. 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
  34. 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.
  35. 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.
  36. === 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
  37. 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
  38. Export PPT Aufgabe: Powerpoint in Doku integrieren: § Sprechernotizen enthalten

    asciidoc § Slides und asciidoc werden automatisch exportiert
  39. 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
  40. Confluence § Aber alle anderen Dokumente sind in Confluence… §

    Confluence speichert die Seiten intern als xhtml § …und hat eine REST-API § et voilá…
  41. Broken Links §...immer wieder mit Probleme bei Dateinamen oder Hyperlinks

    §Lösung: automatisierte Tests! §Inhaltliche Fehler (praktisch) nicht testbar...
  42. 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