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

Architekturdokumentation am (Riesen) Beispiel

Architekturdokumentation am (Riesen) Beispiel

Zeigt eine AsciiDoc-basierte Werkzeugkette (docToolChain) zur Erstellung + Pflege von Architekturdokumentation.

JAX 2017, von Ralf. D. Müller und Gernot Starke

Dr. Gernot Starke

May 10, 2017
Tweet

More Decks by Dr. Gernot Starke

Other Decks in Programming

Transcript

  1. Dr. Gernot Starke innoQ Fellow Softwarearchitektur § Entwurf § Evolution

    + Modernisierung § Dokumentation § Reviews +49 177 7282570 [email protected]
  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. Das erwartet Sie ! §praktische Architekturdokumentation §Tipps zu arc42 und

    docs-like-code §Experimentelle Features :-) §Vorschläge aus Erfahrung NSB (No Silver Bullet)
  4. Das VENOM Projekt § VEry NOrMal System § Gewachsene Dokumentation

    § Unterschiedliche Stakeholder § Aufgrund verschiedener Änderungen stets im Wandel § Hoher Pflegeaufwand
  5. Darf ich vorstellen? Geoff – Solution Architect §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 • MS Word: etablierter Standard • arc42

    in vielen Formaten: • docx • asciidoc • markdown • latex • html • textile • confluence
  10. arc42 Formate §AsciiDoc aus unserer Sicht flexibelstes Format §In alle

    anderen Formate (fast verlustfrei) transformierbar, daher immer „Plan B“
  11. 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 – eine erste Konvertierung
  12. 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
  13. Tools zur Konvertierung §Geringste Einstiegshürde: Gradle und asciidoctorj §Maven ist

    aufwändiger, gut unterstützt §Gradle bezüglich weiterer Build-Steps flexibler
  14. 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.
  15. 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]
  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. 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 ----
  19. 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!
  20. Diagramme § Im Zweifel Pfeile immer vom Aufrufenden zum Aufgerufenen

    § Noch keinen eigenen Stil gefunden? => C4 von Simon Brown ist ein guter Start http://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html
  21. 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.
  22. 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.
  23. === 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
  24. 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
  25. Export PPT Aufgabe: Powerpoint in Doku integrieren: § Sprechernotizen enthalten

    asciidoc § Slides und asciidoc werden automatisch exportiert
  26. Confluence § Aber alle anderen Dokumente sind in Confluence… §

    Confluence speichert die Seiten intern als xhtml § …und hat eine REST-API § et voilá…
  27. 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
  28. 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