Slide 1

Slide 1 text

Dr. Gernot Starke arc42 – die Achte

Slide 2

Slide 2 text

Dr. Gernot Starke INNOQ Fellow üArchitektur-Verbesserer üCoach, Trainer ü arc42, aim42 ü iSAQB

Slide 3

Slide 3 text

Download Voucher für das arc42 by Example eBook: (gültig bis 1. März 2022) https://leanpub.com/arc42byexample/c/arc42-OOP-2022

Slide 4

Slide 4 text

TL;DR Template strukturell identisch zu V 7.0 (Noch) bessere Dokumentation. Integrierte Beispiele.

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

Hast Du 2005 schon in der IT gearbeitet? https://www.mentimeter.com/s/77350eceb19e4d70 d5510228666168e8

Slide 7

Slide 7 text

2001 - 2004: Template (ohne Namen) Eingesetzt und verfeinert: Gernot: Finanzbehörden, diverse Konzerne Peter : Embedded Realtime Umfeld

Slide 8

Slide 8 text

2005: V 2.0 Logo entworfen von etcetera Werbeagentur, Aachen Website(s) HTML-Export aus Mindmanager

Slide 9

Slide 9 text

2005: V 2.0

Slide 10

Slide 10 text

2008 – erste Publikation

Slide 11

Slide 11 text

2012 V 6.0 Migration: 2012 von Dropbox (kurz) zu Bitbucket 2014 dann zu Github 2014 docx -> asciidoc

Slide 12

Slide 12 text

2014 danke, Ralf! Erster Einsatz doctoolchain von Ralf D. Müller

Slide 13

Slide 13 text

2017 V 7.0 Pragmatische Hilfe für Softwarearchitekten gernot STARKE peter HRUSCHKA https://docs.arc42.org https://faq.arc42.org

Slide 14

Slide 14 text

2019-2021

Slide 15

Slide 15 text

2022 V 8.0 • Struktur belassen • Einsatz vereinfachen • Mehr Klarheit bei Lizenz • Weitere Publikationen • Bekannte Fehler beim Einsatz vermeiden (aka “Empfehlungen“)

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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?

Slide 20

Slide 20 text

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!

Slide 21

Slide 21 text

Einsatz vereinfachen... Beispiele! Anwender:innen wollen Beispiele statt methodische Erklärungen.

Slide 22

Slide 22 text

Einsatz vereinfachen... Beispiele! Anwender:innen wollen Beispiele statt methodische Erklärungen. https://docs.arc42.org

Slide 23

Slide 23 text

Einsatz vereinfachen... Beispiele! Anwender:innen wollen Beispiele statt methodische Erklärungen. https://docs.arc42.org

Slide 24

Slide 24 text

Beispiele integriert Beispiele! https://docs.arc42.org

Slide 25

Slide 25 text

Beispiele ... https://docs.arc42.org

Slide 26

Slide 26 text

Weitere Publikationen... https://youtu.be/2tlg0B60ef8 > 4000 views

Slide 27

Slide 27 text

Weitere Publikationen... https://youtu.be/78KJt4EOfFE > 1900 views

Slide 28

Slide 28 text

Weitere Publikationen... https://www.innoq.com/en/articles/2022/01/principles-of-technical-documentation/ > 1400 views

Slide 29

Slide 29 text

No content

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

Empfehlungen in V8 • Weniger Sichten, mehr Konzepte • Architekturentscheidungen ernst(er) nehmen • An Beispielen orientieren

Slide 32

Slide 32 text

Mehr Konzepte, weniger Sichten • Bausteinsicht in der Praxis häufig „übertrieben“ detailliert -> schwer wartbar • Daher: arc42-Empfehlung zu mehr Konzepten und „sparsamen“ Bausteinsichten

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

Architekturentscheidungen # Titel ## Status ## Kontext ## Entscheidung ## Konsequenzen Ergänzung: timestamp

Slide 36

Slide 36 text

ADR Example https://github.com/npryce/adr-tools

Slide 37

Slide 37 text

adr-tools https://github.com/npryce/adr-tools

Slide 38

Slide 38 text

docs.arc42.org offizielle Doku!

Slide 39

Slide 39 text

Was kann arc42 NOCH als Unterstützung tun?

Slide 40

Slide 40 text

Fragen?

Slide 41

Slide 41 text

Thanx. Gernot Starke [email protected] Twitter: @gernotstarke www.innoq.com