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

© Fraunhofer IESE 2 SOME BASICS

© 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)

© Fraunhofer IESE 4 Some Basics Architecture ≠ Architecture Documentation

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

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

© 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

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

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

© Fraunhofer IESE 13 7 ANTI PATTERNS AND TIPS FOR IMPROVEMENT

© Fraunhofer IESE 14 ANTI PATTERN 1 NO ARCHITECTURE DOCUMENTATION

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

© 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

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

© 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

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

© Fraunhofer IESE 20 No Goal State: Impact

© 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

© 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

© 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.

© 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

© Fraunhofer IESE 26 ANTI PATTERN 2 ARCHITECTURE DOCUMENTATION AS DELIVERABLE

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

© 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.”

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

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

© 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.

© 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

© 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

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

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

© 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

Can it really be distinguished? Yes.

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

© 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

© 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

© 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

© Fraunhofer IESE 42 Example Runtime Diagram

© Fraunhofer IESE 43 Example Devtime Diagram

© 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.

© 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

© 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/

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

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

© 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!)

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

© 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

© 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

© 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

© Fraunhofer IESE 56 ANTI PATTERN 5 LACKING CONNECTION TO CODE

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

© 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

© 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

© 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

© 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

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

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

© 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, …

© 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

© 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

© 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

© 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

© Fraunhofer IESE 69 ANTI PATTERN 7 MESSY DIAGRAMS

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

© 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

© 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

© 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

© 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

© Fraunhofer IESE 75 CONCLUSION

© 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

© Fraunhofer IESE 77 architecture@iese.fraunhofer.de architecture.iese.fraunhofer.de Architecture-Centric Engineering Dr. Dominik Rost +49 631 6800 2243 dominik.rost@iese.fraunhofer.de @domrost Dr. Matthias Naab +49 631 6800 2249 matthias.naab@iese.fraunhofer.de SEACON - Vortragsbewertung