arc42 die Achte

Überblick über Historie von arc42 sowie die Neuerungen von Version 8, die seit Anfang 2022 "live" ist.

Transcript

1. Dr. Gernot Starke arc42 – die Achte
2. Dr. Gernot Starke INNOQ Fellow üArchitektur-Verbesserer üCoach, Trainer ü arc42, aim42 ü iSAQB
3. Download Voucher für das arc42 by Example eBook: (gültig bis 1. März 2022) https://leanpub.com/arc42byexample/c/arc42-OOP-2022
4. TL;DR Template strukturell identisch zu V 7.0 (Noch) bessere Dokumentation. Integrierte Beispiele.
5. 2005 bis heute 2012 2005 2010 2015 V 7.0 V 6.0 Pragmatische Hilfe für Softwarearchitekten gernot STARKE peter HRUSCHKA 2017 2019 V 2.0 V 5.0 2021 2022 V 8.0 2008
6. Hast Du 2005 schon in der IT gearbeitet? https://www.mentimeter.com/s/77350eceb19e4d70 d5510228666168e8
7. 2001 - 2004: <no name> Template (ohne Namen) Eingesetzt und verfeinert: Gernot: Finanzbehörden, diverse Konzerne Peter : Embedded Realtime Umfeld
8. 2005: V 2.0 Logo entworfen von etcetera Werbeagentur, Aachen Website(s) HTML-Export aus Mindmanager
9. 2005: V 2.0
10. 2008 – erste Publikation
11. 2012 V 6.0 Migration: 2012 von Dropbox (kurz) zu Bitbucket 2014 dann zu Github 2014 docx -> asciidoc
12. 2014 danke, Ralf! Erster Einsatz doctoolchain von Ralf D. Müller
13. 2017 V 7.0 Pragmatische Hilfe für Softwarearchitekten gernot STARKE peter HRUSCHKA https://docs.arc42.org https://faq.arc42.org
14. 2019-2021
15. 2022 V 8.0 • Struktur belassen • Einsatz vereinfachen • Mehr Klarheit bei Lizenz • Weitere Publikationen • Bekannte Fehler beim Einsatz vermeiden (aka “Empfehlungen“)
16. Suchbild... 11. Risks & Technical Debt ARC42 Architecture Documentation 1. Introduction and Goals 2. Constraints 3. Scope & Context 5. Building Block View 6. Runtime View 7. Deployment View 8. Crosscutting Concepts 1. Goals and Requirements 2. Constraints 3. Scope / Context 4. Solution / Approach 4a Structures & Process 4b Samples incl. Code 5. Alternatives 6. Risks Structure of Concepts 1. What to decide? 1.1 In what context? 2. How was decided? 2.1 Why? 2.2 Assumptions 2.3 Discarded Alternatives 3. Consequences? 4. Known Risks? 5. Who has decided? Structure of Architecture Decisions 10. Quality Scenarios 9. Architecture Decisions arc42 V 7.0 (2017), BigPicture created by Peter Hruschka & Gernot Starke Stakeholder Table Who? Interest? ... ... 1. Useage Scenarios 2. Change Scenarios Scenarios to define Quality Requirements Quality Goals Goal Description ... ... Deployment View Runtime View 1. Name, Version 2. Ressources (Syntax) 3. Semantic 3.1 Business 3.2 Technical 4. Protocol 4.1 Flow / Process 4.2 Transmission Channel 5. Error and Exception Behavior 6. Restrictions 7. Sample Data 8. Quality Attributes / QoS Structure of Interface Descriptions 1. Name 2. Purpose / Responsibility 3. Interfaces 4. Location / Files 5. Fulfilled Requirements 6. Open Issues Blackbox-Template 1. Name 2. Overview (Diagram!) 3. Motivation, Rationale 4. Contained Blackboxes 5. Internal Interfaces 6. Open issues Whitebox-Template Scope & Context 4. Solution Strategy business technical 12. Glossary Building Block View ... ... Logging Sicherheit Transaktionen Ergonomie Persistenz ... ... Logging UI / UX Persistence Patterns Domain Model Crosscutting Concepts 11. Risks & Technical Debt ARC42 Architecture Documentation 1. Introduction and Goals 2. Constraints 3. Scope & Context 5. Building Block View 6. Runtime View 7. Deployment View 8. Crosscutting Concepts 1. Goals and Requirements 2. Solution / Approach 2a Structures & Process 2b Samples incl. Code 3. Alternatives 4. Risks Structure of Concepts 1. Title 2. Context / Situation 3. Decision 4. Status 5. Consequences Structure of Architecture Decisions (ADRs) 10. Quality Scenarios 9. Architecture Decisions arc42 V 8.0 (2022), BigPicture by Gernot Starke & Peter Hruschka Stakeholder Table Who? Interest? ... ... 1. Useage Scenarios 2. Change Scenarios Scenarios to specify Quality Requirements Quality Goals Goal Description ... ... Deployment View Runtime View 1. Name, Version 2. Syntax 3. Semantic 4. Protocol 5. Error and Exception Behavior 6. Sample Data 7. Quality Attributes Structure of Interface Descriptions 1. Name 2. Purpose / Responsibility 3. Interfaces 4. Location / Files Blackbox-Template 1. Name 2. Overview (Diagram!) 3. Motivation, Rationale 4. Contained Blackboxes 5. Internal Interfaces Whitebox-Template Scope & Context 4. Solution Strategy business technical 12. Glossary Building Block View ... ... Logging Sicherheit Transaktionen Ergonomie ... ... Logging UI / UX Persistence Crosscutting Concepts ??
17. V 7 und V 8 11. Risks & Technical Debt ARC42 Architecture Documentation 1. Introduction and Goals 2. Constraints 3. Scope & Context 5. Building Block View 6. Runtime View 7. Deployment View 8. Crosscutting Concepts 1. Goals and Requirements 2. Solution / Approach 2a Structures & Process 2b Samples incl. Code 3. Alternatives 4. Risks Structure of Concepts 1. Title 2. Context / Situation 3. Decision 4. Status 5. Consequences Structure of Architecture Decisions (ADRs) 10. Quality Scenarios 9. Architecture Decisions arc42 V 8.0 (2022), BigPicture by Gernot Starke & Peter Hruschka Stakeholder Table Who? Interest? ... ... 1. Useage Scenarios 2. Change Scenarios Scenarios to specify Quality Requirements Quality Goals Goal Description ... ... Deployment View Runtime View 1. Name, Version 2. Syntax 3. Semantic 4. Protocol 5. Error and Exception Behavior 6. Sample Data 7. Quality Attributes Structure of Interface Descriptions 1. Name 2. Purpose / Responsibility 3. Interfaces 4. Location / Files Blackbox-Template 1. Name 2. Overview (Diagram!) 3. Motivation, Rationale 4. Contained Blackboxes 5. Internal Interfaces Whitebox-Template Scope & Context 4. Solution Strategy business technical 12. Glossary Building Block View ... ... Logging Sicherheit Transaktionen Ergonomie ... ... Logging UI / UX Persistence Crosscutting Concepts
18. V 7 und V 8 11. Risks & Technical Debt ARC42 Architecture Documentation 1. Introduction and Goals 2. Constraints 3. Scope & Context 5. Building Block View 6. Runtime View 7. Deployment View 8. Crosscutting Concepts 1. Goals and Requirements 2. Solution / Approach 2a Structures & Process 2b Samples incl. Code 3. Alternatives 4. Risks Structure of Concepts 1. Title 2. Context / Situation 3. Decision 4. Status 5. Consequences Structure of Architecture Decisions (ADRs) 10. Quality Scenarios 9. Architecture Decisions arc42 V 8.0 (2022), BigPicture by Gernot Starke & Peter Hruschka Stakeholder Table Who? Interest? ... ... 1. Useage Scenarios 2. Change Scenarios Scenarios to specify Quality Requirements Quality Goals Goal Description ... ... Deployment View Runtime View 1. Name, Version 2. Syntax 3. Semantic 4. Protocol 5. Error and Exception Behavior 6. Sample Data 7. Quality Attributes Structure of Interface Descriptions 1. Name 2. Purpose / Responsibility 3. Interfaces 4. Location / Files Blackbox-Template 1. Name 2. Overview (Diagram!) 3. Motivation, Rationale 4. Contained Blackboxes 5. Internal Interfaces Whitebox-Template Scope & Context 4. Solution Strategy business technical 12. Glossary Building Block View ... ... Logging Sicherheit Transaktionen Ergonomie ... ... Logging UI / UX Persistence Crosscutting Concepts
19. Lizenz... V 7.0 und vorher: arc42 is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. Under this license, you’re free to: • Share: copy and redistribute the material in any medium or format • Adapt: remix, transform, and build upon the material for any purpose, even commercially. unklar: Gilt das für Template, und/oder auch für Inhalte eigener Dokumentation?
20. V8: Klarheit bei Lizenz ab V 8.0: The arc42 template itself is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. You are completely free to use or publish your own content, even if it is embedded in the arc42 template, according to your own rules. unklar: eigene Inhalte sind (natürlich) von der arc42 Lizenz NICHT betroffen!
21. Einsatz vereinfachen... Beispiele! Anwender:innen wollen Beispiele statt methodische Erklärungen.
22. Einsatz vereinfachen... Beispiele! Anwender:innen wollen Beispiele statt methodische Erklärungen. https://docs.arc42.org
23. Einsatz vereinfachen... Beispiele! Anwender:innen wollen Beispiele statt methodische Erklärungen. https://docs.arc42.org
24. Beispiele integriert Beispiele! https://docs.arc42.org
25. Beispiele ... https://docs.arc42.org
26. Weitere Publikationen... https://youtu.be/2tlg0B60ef8 > 4000 views
27. Weitere Publikationen... https://youtu.be/78KJt4EOfFE > 1900 views
28. Weitere Publikationen... https://www.innoq.com/en/articles/2022/01/principles-of-technical-documentation/ > 1400 views
30. Weitere Publikationen... FACHTHEMA arc42 Die Antwort auf alle Fragen zur Dokumentation arc42, die Achte Gernot Starke Für das ungeliebte Thema „Dokumentation" gibt es seit Jahren ein praktisches Helferlein aus der Open-Source-Ecke: arc42. An- fang 2022 erscheint die Version 8. Das nehme ich zum Anlass, Ihnen hier eine kurze Einführung in arc42 zu geben, einige Tipps zum praktischen Einsatz sowie einen Überblick über die Neue- rungen von V8. Das Vorbild war Volere [Vol], ein Template für Software-Requi- rements, das sich flexibel in beliebigen Entwicklungsprojekten zur Kommunikation und Dokumentation von Anforderungen (= dem Problemraum) einsetzen lässt. Peter und Gernot haben mit arc42 das Pendant für den Lösungsraum (== die Architektur) entwickelt. Von Beginn an stand das Vorhaben unter der Prämisse, arc42 kom- plett Open Source (siehe [GitHarc42]) zu entwickeln und frei ver- fügbar anzubieten. In zahlreichen Unternehmen gehört arc42 (siehe [arc42]) heute zu den etablierten Hilfsmitteln für die Entwicklung, Kommunikation und Dokumentation von Softwarearchitekturen. arc42 ist ein prag- matisches Template, gedacht für alle Beteiligten an Software- und Systementwicklung. Sie können arc42 komplett frei verwenden, da es unter einer liberalen Open-Source-Lizenz erstellt und publiziert wird. arc42 stammt aus der Praxis und basiert auf Erfahrungen in- ternationaler Architekturprojekte und Rückmeldungen vieler An- wenderinnen und Anwender. Ach ja, 42: Die etwas ältere Generation von Softwerkern mag den schrulligen britischen Science-Fiction-Autor Douglas Adams noch kennen, Douglas hat „Per Anhalter durch die Galaxis" [Wiki] geschrieben, in dem die Zahl 42 als die Antwort auf die „Ultima- tive Frage des Lebens, des Universums und dem ganzen Rest" er- scheint. arc42 soll für Ihre Systeme und Softwarearchitekturen die Antworten zumindest auf viele Fragen bezüglich Architektur- und Lösungsentscheidungen bereithalten. arc42 eignet sich für beliebige Technologien und Werkzeuge. Es passt großartig zu agilen und iterativen Entwicklungsvorgehen, aber auch andere Organisationsformen profitieren davon. Neben dem Template schlägt arcá2 einige Kernaufgaben zur Entwicklung Der Architektur-Schrank Vergleichen Sie arc42 mit einem Schubladenschrank: Die Schubla- und Konstruktion effektiver Softwarearchitekturen vor, auf die ich in diesem Artikel allerdings nicht weiter eingehe. den sind ordentlich beschriftet und enthalten zusammengehörige Informationen. arc42 enthält zwölf solche Fächer (s. Abb. 1). Die Bedeutung dieserarc42-Fächerist leicht verständlich. arc42 stammt von Dr. Gernot Starke und Dr. Peter Hruschka: Wir beide haben 2002 angefangen, unsere Erfahrungen vieler Ent- arc42 gibt Ihnen damit eine einfache, klare Struktur zur Be- wicklungs- und Architekturprojekte zusammenzutragen und eine flexibel wiederverwendbare Informationsstruktur (.Template") zu entwickeln. schreibung Ihrer (komplexen!) Systeme. Beginnend bei den Zielen und Anforderungen an Ihr System und die Einbettung in die fachli- che und technische Umgebung, können Sie nahezu alle Beteiligten 38 JavasPEKTRUM 1/2022 JavaSPEKTRUM 01/2022
31. Empfehlungen in V8 • Weniger Sichten, mehr Konzepte • Architekturentscheidungen ernst(er) nehmen • An Beispielen orientieren
32. Mehr Konzepte, weniger Sichten • Bausteinsicht in der Praxis häufig „übertrieben“ detailliert -> schwer wartbar • Daher: arc42-Empfehlung zu mehr Konzepten und „sparsamen“ Bausteinsichten
33. 1. Ein ührung und Ziele 6. Laufzeitsicht 8. Konzepte 10. Qualitätsszenarien 4. Lösungsstrategie 12. Glossar 7. Verteilungssicht 5. Bausteinsicht 3. Kontextabgrenzung 2. Randbedingungen 9. Architektur- entscheidungen 11. Risiken & technische Schulden 8. Konzepte 8.1 Report 8.2 Batch 8.3 Mobile-UI … Mehr Konzepte, wie geht das? • In Sichten auf Konzepte verweisen, durch z.B. ≪konzept-name≫ someWhitebox Customer «Mobile-UI» Planning «Batch» Adress- validierung «Report» Sales FooApp Competition
34. Architekturentscheidungen ernst(er) nehmen • ADRs (Architecture Decision Records) bisher nur „Nischen-Dasein“ • Vorschlag für ADR-Struktur (nach M.Nygard) • Mehr Tipps zu ADRs ADRs sind sparsame Dokumentation
35. Architekturentscheidungen # Titel ## Status ## Kontext ## Entscheidung ## Konsequenzen Ergänzung: timestamp
36. ADR Example https://github.com/npryce/adr-tools
37. adr-tools https://github.com/npryce/adr-tools
38. docs.arc42.org offizielle Doku!
39. Was kann arc42 NOCH als Unterstützung tun?
40. Fragen?
41. Thanx. Gernot Starke gernot.starke@innoq.com Twitter: @gernotstarke www.innoq.com