Slide 1

Slide 1 text

© Fraunhofer IESE 1 Matthias Naab Dominik Rost OOP 2022 | Online Meisterwerk oder Groschenroman? 7 Anti-Patterns und Tipps für gute Architektur-Dokumentationen

Slide 2

Slide 2 text

© Fraunhofer IESE 2 SOME BASICS

Slide 3

Slide 3 text

© Fraunhofer IESE 3 Some Basics An Architecture Description (≙ Architecture Documentation) is a work product used to express the Architecture of some System Of Interest. (ISO/IEC/IEEE 42010)

Slide 4

Slide 4 text

© Fraunhofer IESE 4 Some Basics Architecture ≠ Architecture Documentation

Slide 5

Slide 5 text

© Fraunhofer IESE 5 Some Basics System (Code + Infrastructure) Architecture Architecture Documentation has an describes

Slide 6

Slide 6 text

© Fraunhofer IESE 6 MOTIVATION WHY DO WE CREATE ARCHITECTURE DOCUMENTATION?

Slide 7

Slide 7 text

© Fraunhofer IESE 10 Goals for Architecture Documentation Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work

Slide 8

Slide 8 text

© Fraunhofer IESE 11 Motivation for this Talk We see great architectures much more often than great architecture documentation.

Slide 9

Slide 9 text

© Fraunhofer IESE 12 Anti Pattern #:    

Slide 10

Slide 10 text

© Fraunhofer IESE 13 7 ANTI PATTERNS AND TIPS FOR IMPROVEMENT

Slide 11

Slide 11 text

© Fraunhofer IESE 14 ANTI PATTERN 1 NO ARCHITECTURE DOCUMENTATION

Slide 12

Slide 12 text

© Fraunhofer IESE 15 Anti Pattern 1: No Architecture Documentation Photo by Joan Gamell on Unsplash Code is the only Truth!

Slide 13

Slide 13 text

© Fraunhofer IESE 16 Anti Pattern 1: No Architecture Documentation – Description Many important kinds of information are not conveyed in source code  Goal state  Decisions and rationale  Abstraction and Focus

Slide 14

Slide 14 text

© Fraunhofer IESE 17 No Goal State: Intended Architecture vs Implemented Architecture System (Code + Infrastructure) Architecture Architecture Documentation has an describes

Slide 15

Slide 15 text

© Fraunhofer IESE 18 No Goal State: Intended Architecture vs Implemented Architecture System (Code + Infrastructure) Implemented Architecture Architecture Documentation has an describes Intended Architecture prescribes describes should conform to

Slide 16

Slide 16 text

© Fraunhofer IESE 19 No Goal State: Impact Photo by John Schnobrich on Unsplash I can always explain the concept!

Slide 17

Slide 17 text

© Fraunhofer IESE 20 No Goal State: Impact

Slide 18

Slide 18 text

© Fraunhofer IESE 21 No Decisions and Rationale: Impact How did we decide this? Why did we decide it that way? Did we miss this point? Doesn’t it make more sense this way? Let’s change it. Three weeks later

Slide 19

Slide 19 text

© Fraunhofer IESE 23 Impact on Goals for Architecture Documentation Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work

Slide 20

Slide 20 text

© Fraunhofer IESE 24 Anti Pattern 1: No Architecture Documentation – Tips for Improvement  Create architecture documentation ;)  Describe what the code does not.  Reduce to the essentials & transport clear messages.  Document decisions.

Slide 21

Slide 21 text

© Fraunhofer IESE 25 Tips for Improvement – Architecture Decision Records  Example Architecture Decision Record Template         More Information  https://github.com/adr  https://github.com/joelparkerhenderson/architecture-decision-record

Slide 22

Slide 22 text

© Fraunhofer IESE 26 ANTI PATTERN 2 ARCHITECTURE DOCUMENTATION AS DELIVERABLE

Slide 23

Slide 23 text

© Fraunhofer IESE 27 Anti Pattern 2: Architecture Documentation as Deliverable Photo by Alvaro Reyes on Unsplash TODO: Document the architecture

Slide 24

Slide 24 text

© Fraunhofer IESE 28 Anti Pattern 2: Architecture Documentation as Deliverable – Description Project Start Create initial design of architecture Deliver to Customer Build software Packaging and QA “Oops, we also promised an architecture documentation.”

Slide 25

Slide 25 text

© Fraunhofer IESE 29 Anti Pattern 2: Architecture Documentation as Deliverable – Example

Slide 26

Slide 26 text

© Fraunhofer IESE 30 Anti Pattern 2: Architecture Documentation as Deliverable – Description Reverse Engineering Tool System Artifacts Architecture Model Architecture Documentation

Slide 27

Slide 27 text

© Fraunhofer IESE 31 Anti Pattern 2: Architecture Documentation as Deliverable – Impact  Architecture (documentation) is not an end in itself.  Architecture is an investment that must pay off.  Creating architecture documentation as a deliverable, creates the cost but does not yield the benefits.

Slide 28

Slide 28 text

© Fraunhofer IESE 32 Impact on Goals for Architecture Documentation Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work

Slide 29

Slide 29 text

© Fraunhofer IESE 33 Anti Pattern 2: Architecture Documentation as Deliverable – Tips for Improvement  Architecture work and decision making is done anyways during the project.  Make it explicit and integrate architecture documentation into the development process.  Benefit from explicit architecture concepts and ideas. Project Start Create initial design of architecture Deliver to Customer Build software Packaging and QA Create and maintain architecture documentation

Slide 30

Slide 30 text

© Fraunhofer IESE 34 ANTI PATTERN 3 NO RUNTIME / DEVTIME DIFFERENTIATION

Slide 31

Slide 31 text

© Fraunhofer IESE 35 Anti Pattern 3: No RT/DT-Differentiation Photo by Flo Karr & Christina @ wocintechchat.com on Unsplash What’s the difference?

Slide 32

Slide 32 text

© Fraunhofer IESE 36 Anti Pattern 3: No RT/DT-Differentiation – Description Runtime Devtime System in Action/Execution Functional Interacting Entities Resident in System Memory Team in Action Code & Infrastructure Artifacts Resident in Dev Environment

Slide 33

Slide 33 text

Can it really be distinguished? Yes.

Slide 34

Slide 34 text

© Fraunhofer IESE 38 Runtime and Devtime Entities might be the same … Runtime Devtime IDE System Chat Event Processor Chat Event Processor

Slide 35

Slide 35 text

© Fraunhofer IESE 39 … but they need not to be the same! Runtime Devtime IDE System Chat Event Processor Chat Event Processor Event Bus Chat Event Processor API DB Chat Event Processor

Slide 36

Slide 36 text

© Fraunhofer IESE 40 … but they need not to be the same! Runtime Devtime IDE System Chat Event Processor Node 1 Node 2 Node 3 Node 4

Slide 37

Slide 37 text

© Fraunhofer IESE 41 … but they need not to be the same! Runtime Devtime IDE System Chat Event Processor Node 1 Node 2 Node 3 Node 4 Abstract Event Processor Event Processor Library

Slide 38

Slide 38 text

© Fraunhofer IESE 42 Example Runtime Diagram

Slide 39

Slide 39 text

© Fraunhofer IESE 43 Example Devtime Diagram

Slide 40

Slide 40 text

© Fraunhofer IESE 46 Anti Pattern 3: No RT/DT-Differentiation - Impact  RT and DT are almost never explicitly differentiated in architecture documentation.  People are hardly ever aware of the differences.  Architecture descriptions and diagrams become more imprecise than necessary.  Important elements and interactions might be missed.

Slide 41

Slide 41 text

© Fraunhofer IESE 47 Impact on Goals for Architecture Documentation Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work

Slide 42

Slide 42 text

© Fraunhofer IESE 48 Anti Pattern 3: No RT/DT-Differentiation – Tips for Improvement  Make it clear (to yourself and others), what you depict and describe.  Tag diagrams to make RT / DT explicit.  Use the corresponding elements of the respective side (e.g. components for RT, modules for DT).  Understand, RT views are not just about sequence diagrams.  Use a view type framework, which explicitly differentiates RT / DT, such as ADF.   https://www.iese.fraunhofer.de/blog/softwarearchitekturen-einfacher-designen-und- verstaendlicher-dokumentieren-mit-dem-fraunhofer-adf/

Slide 43

Slide 43 text

© Fraunhofer IESE 49 ANTI PATTERN 4 TECH-ONLY ARCHITECTURE DOCUMENTATION

Slide 44

Slide 44 text

© Fraunhofer IESE 50 Anti Pattern 4: Tech-Only Architecture Documentation Tech is king!

Slide 45

Slide 45 text

© Fraunhofer IESE 51 Anti Pattern 4: Tech-Only Architecture Documentation – Description App Portal App Framework App Framework App Framework Service Mesh Backends Backends GraphQL Server GraphQL Server Gateway App App App App App App App  Only technological elements  No functional decomposition (often, it just does not exist!)

Slide 46

Slide 46 text

© Fraunhofer IESE 52 Anti Pattern 4: Tech-Only Architecture Documentation – Description  Data is highly underrepresented Where to find Data in a Typical Architecture Document? Where is Data really?

Slide 47

Slide 47 text

© Fraunhofer IESE 53 Anti Pattern 4: Tech-Only Architecture Documentation – Impact  Unclear decomposition of functionality  Unclear decomposition and handling of data  Unclear mapping of functionality to technology components  Unclear interaction about components  Unclear granularity of elements (e.g. services, apps, …)  Impossible reasoning about quality attributes  Unclear design rationales  Missing guidance

Slide 48

Slide 48 text

© Fraunhofer IESE 54 Impact on Goals for Architecture Documentation Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work

Slide 49

Slide 49 text

© Fraunhofer IESE 55 Anti Pattern 4: Tech-Only Architecture Documentation – Tips for Improvement  Document architecture drivers as scenarios  Describe functional decomposition  E.g. based on the ideas of DDD  Describe data decomposition and handling aspects  Data models | Data representations | Data transformations | Data storage  Describe mapping of functional components to technologies  Consider both: runtime & devtime aspects

Slide 50

Slide 50 text

© Fraunhofer IESE 56 ANTI PATTERN 5 LACKING CONNECTION TO CODE

Slide 51

Slide 51 text

© Fraunhofer IESE 57 Anti Pattern 5: Lacking Connection to Code Between two worlds Photo by Alex Radelich on Unsplash

Slide 52

Slide 52 text

© Fraunhofer IESE 58 Anti Pattern 5: Lacking Connection to Code – Description  Often, connection of architectural elements to code is missing  Reasons  Too much focus on technology (Anti Pattern 4)  Missing separation of runtime and devtime (Anti Pattern 3)  Devtime not documented at all  No uniform naming  Additionally: missing link between implemented architecture and intended architecture System (Code + Infrastructure) Architecture Architecture Documentation has an describes

Slide 53

Slide 53 text

© Fraunhofer IESE 59 Anti Pattern 5: Lacking Connection to Code – Impact  Questions remaining unanswered  How is a component realized?  Where can the code be found belonging to a component?  Developers do not trust the architecture  Developers see the architecture as “ivory tower” work  Developers find their own ways to realize the system  Impact of architecture work as a whole degrades

Slide 54

Slide 54 text

© Fraunhofer IESE 60 Impact on Goals for Architecture Documentation Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work

Slide 55

Slide 55 text

© Fraunhofer IESE 61 Anti Pattern 5: Lacking Connection to Code – Tips for Improvement  Apply “architecture-evident coding” https://resources.sei.cmu.edu/asset_files/Presentation/2013_017_001_48651.pdf  Explicitly include devtime views  Explicitly include package mapping  Explicitly include name mapping  Express mapping as rules  Aim at uniformity

Slide 56

Slide 56 text

© Fraunhofer IESE 62 ANTI PATTERN 6 OVER-FOCUSED ON TEMPLATES AND VIEWS

Slide 57

Slide 57 text

© Fraunhofer IESE 63 Anti Pattern 6: Over-Focused on Templates and Views Focus on templates instead of readers

Slide 58

Slide 58 text

© Fraunhofer IESE 64 Anti Pattern 6: Over-Focused on Templates and Views – Description  Examples:  arc42  ISO42010 Templates  Templates can be a good guidance, but …  Just filling the template kills creativity and adequacy for target groups  Templates partially use misleading view names  Conceptual view, logical view, building block view, …

Slide 59

Slide 59 text

© Fraunhofer IESE 65 Anti Pattern 6: Over-Focused on Templates and Views – Description  Observations in practice  Only small number of diagrams in each view  No diagrams for explanation in crosscutting concepts  More focus on filling the views than on representing the right information for readers in a readable storyline Context and Scope Building Block View Runtime View Deployment View Crosscutting Concepts

Slide 60

Slide 60 text

© Fraunhofer IESE 66 Anti Pattern 6: Over-Focused on Templates and Views – Impact  For architects  Positive  Quite appropriate for learning  Quite appropriate for simple architectures  Negative  Believe to be finished when all views are filled in  too few diagrams  Aspects not listed are ignored (e.g. data)  Distracted from the system itself  For readers  Positive  Uniform document structures  Negative  The more complicated a system the more counterintuitive it is to organize it along view types  Hard to read

Slide 61

Slide 61 text

© Fraunhofer IESE 67 Impact on Goals for Architecture Documentation Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work

Slide 62

Slide 62 text

© Fraunhofer IESE 68 Anti Pattern 6: Over-Focused on Templates and Views – Tips for Improvement  Do not use a fixed table of contents  Organize along the leading concepts of your system  Present a readable story with clear navigation  Rules for guidance  Context before internals  Runtime before devtime  Functionality & data before quality attributes  Use views and diagrams to illustrate concepts  Combine general decomposition with quality-driven concepts  More guidance: https://www.iese.fraunhofer.de/blog/softwarearchitekturen-einfacher-designen-und-verstaendlicher-dokumentieren-mit-dem-fraunhofer-adf Context and Scope Initial System Decomposition in Domains Logistics Domain - Data Decomposition Event Orientation as Core Communication Concept Cloud Deployment & Technologies Project Structure Example Structure Scalability & Availability Concepts Performance Concepts Internal Layer Structure Describe with appropriate views and diagrams Functionality & Data Functionality & Data Quality Attributes

Slide 63

Slide 63 text

© Fraunhofer IESE 69 ANTI PATTERN 7 MESSY DIAGRAMS

Slide 64

Slide 64 text

© Fraunhofer IESE 70 Anti Pattern 7: Messy Diagrams Huh?

Slide 65

Slide 65 text

© Fraunhofer IESE 71 Anti Pattern 7: Messy Diagrams – Description  Diagrams too large  Diagrams mix up content  Diagrams not well readable  Diagrams not adequate for readers  Diagrams without clear semantics

Slide 66

Slide 66 text

© Fraunhofer IESE 72 Anti Pattern 7: Messy Diagrams – Impact  Diagrams are hard to read  Diagrams are hard to interpret  Diagrams are hard to understand  Diagrams are hard to memorize  Concepts across diagrams are hard to recognize  Architecture documentation is misunderstood

Slide 67

Slide 67 text

© Fraunhofer IESE 73 Impact on Goals for Architecture Documentation Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work

Slide 68

Slide 68 text

© Fraunhofer IESE 74 Anti Pattern 7: Messy Diagrams – Tips for Improvement  Optimize diagrams for readers  Keep diagrams concise  Use a legend for diagrams  Use a recurring layout, topology, and coloring  Do not use auto-layout!  Name the type of view shown

Slide 69

Slide 69 text

© Fraunhofer IESE 75 CONCLUSION

Slide 70

Slide 70 text

© Fraunhofer IESE 76 Key Take Aways  All anti patterns HARM THE GOALS of architecture documentation  Make sure that your investments pay off  Many anti patterns can be avoided at NO EXTRA COST Make concepts and ideas explicit Make concepts and ideas precise Cover the essential concepts and ideas of the system Create a persistent memory of concepts and decisions over time Create a communication vehicle to convey ideas and enable reasoning Create a common understanding across all stakeholders Become independent of the availability of persons Guide the realization work Create architecture documentation No alibi architecture documentation Runtime & devtime Not only technology Connect to code Focus on readers No messy diagrams

Slide 71

Slide 71 text

© Fraunhofer IESE 77 [email protected] architecture.iese.fraunhofer.de Architecture-Centric Engineering Dr. Dominik Rost +49 631 6800 2243 [email protected] @domrost Dr. Matthias Naab +49 631 6800 2249 [email protected]