SEACON 2022 - Meisterwerk oder Groschenroman - 7 Anti-Pattern und Tipps für gute Architekturdokumentation

Zugegeben, kaum jemand fällt beim Thema Architekturdokumentation vor Begeisterung vom Stuhl, aber spätestens bei mittelgroßen Systemen geht es nicht mehr ohne.
Obwohl Architekturdokumentation eine wichtige Rolle im Entwicklungsprozess einnimmt, wird sie ganz häufig stiefmütterlich behandelt. In unseren Projekten treffen wir viel häufiger auf tolle Architekturen als auf tolle Architekturdokumentationen. Dabei begegnen uns immer wieder die gleichen Defizite: Überbetonung von technischen Aspekten oder Vermischung von Lauf- und Entwicklungszeitaspekten sind nur einige Beispiele.
In diesem Vortrag berichten wir von unseren Erfahrungen rund um Architekturdokumentation von unterschiedlichsten Systemen und Branchen. Wir fassen 7 Anti-Pattern zusammen und geben Tipps wie jede:r durch einfache Mittel die Architekturdokumentation verbessern kann. Unsere Tipps sind unabhängig vom verwendeten Vorgehen und natürlich auch kombinierbar mit Templates wie arc42.

Transcript

1. © Fraunhofer IESE 1 Matthias Naab Dominik Rost SEACON 2022 | Online Meisterwerk oder Groschenroman? 7 Anti-Patterns und Tipps für gute Architektur-Dokumentationen
2. © Fraunhofer IESE 2 SOME BASICS
3. © 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)
4. © Fraunhofer IESE 4 Some Basics Architecture ≠ Architecture Documentation
5. © Fraunhofer IESE 5 Some Basics System (Code + Infrastructure) Architecture Architecture Documentation has an describes
6. © Fraunhofer IESE 6 MOTIVATION WHY DO WE CREATE ARCHITECTURE DOCUMENTATION?
7. © 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
8. © Fraunhofer IESE 11 Motivation for this Talk We see great architectures much more often than great architecture documentation.
9. © Fraunhofer IESE 12 Anti Pattern #: <Anti Pattern Name> ◼ <Description> ◼ <Example> ◼ <Impact> ◼ <Tips for Improvement>
10. © Fraunhofer IESE 13 7 ANTI PATTERNS AND TIPS FOR IMPROVEMENT
11. © Fraunhofer IESE 14 ANTI PATTERN 1 NO ARCHITECTURE DOCUMENTATION
12. © Fraunhofer IESE 15 Anti Pattern 1: No Architecture Documentation Photo by Joan Gamell on Unsplash Code is the only Truth!
13. © 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
14. © Fraunhofer IESE 17 No Goal State: Intended Architecture vs Implemented Architecture System (Code + Infrastructure) Architecture Architecture Documentation has an describes
15. © 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
16. © Fraunhofer IESE 19 No Goal State: Impact Photo by John Schnobrich on Unsplash I can always explain the concept!
17. © Fraunhofer IESE 20 No Goal State: Impact
18. © 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
19. © 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
20. © 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.
21. © Fraunhofer IESE 25 Tips for Improvement – Architecture Decision Records ◼ Example Architecture Decision Record Template ◼ <Decision Name> ◼ <Context and Problem Statement> ◼ <Description/Explanation> ◼ <Rationale> ◼ <Pros> ◼ <Cons & Tradeoffs> ◼ <Discarded Alternatives> ◼ More Information ◼ https://github.com/adr ◼ https://github.com/joelparkerhenderson/architecture-decision-record
22. © Fraunhofer IESE 26 ANTI PATTERN 2 ARCHITECTURE DOCUMENTATION AS DELIVERABLE
23. © Fraunhofer IESE 27 Anti Pattern 2: Architecture Documentation as Deliverable Photo by Alvaro Reyes on Unsplash TODO: Document the architecture
24. © 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.”
25. © Fraunhofer IESE 29 Anti Pattern 2: Architecture Documentation as Deliverable – Example
26. © Fraunhofer IESE 30 Anti Pattern 2: Architecture Documentation as Deliverable – Description Reverse Engineering Tool System Artifacts Architecture Model Architecture Documentation
27. © 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.
28. © 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
29. © 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
30. © Fraunhofer IESE 34 ANTI PATTERN 3 NO RUNTIME / DEVTIME DIFFERENTIATION
31. © Fraunhofer IESE 35 Anti Pattern 3: No RT/DT-Differentiation Photo by Flo Karr & Christina @ wocintechchat.com on Unsplash What’s the difference?
32. © 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
33. Can it really be distinguished? Yes.
34. © Fraunhofer IESE 38 Runtime and Devtime Entities might be the same … Runtime Devtime IDE System Chat Event Processor Chat Event Processor
35. © 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
36. © 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
37. © 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
38. © Fraunhofer IESE 42 Example Runtime Diagram
39. © Fraunhofer IESE 43 Example Devtime Diagram
40. © 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.
41. © 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
42. © 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/
43. © Fraunhofer IESE 49 ANTI PATTERN 4 TECH-ONLY ARCHITECTURE DOCUMENTATION
44. © Fraunhofer IESE 50 Anti Pattern 4: Tech-Only Architecture Documentation Tech is king!
45. © 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!)
46. © 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?
47. © 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
48. © 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
49. © 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
50. © Fraunhofer IESE 56 ANTI PATTERN 5 LACKING CONNECTION TO CODE
51. © Fraunhofer IESE 57 Anti Pattern 5: Lacking Connection to Code Between two worlds Photo by Alex Radelich on Unsplash
52. © 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
53. © 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
54. © 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
55. © 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
56. © Fraunhofer IESE 62 ANTI PATTERN 6 OVER-FOCUSED ON TEMPLATES AND VIEWS
57. © Fraunhofer IESE 63 Anti Pattern 6: Over-Focused on Templates and Views Focus on templates instead of readers
58. © 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, …
59. © 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
60. © 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
61. © 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
62. © 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
63. © Fraunhofer IESE 69 ANTI PATTERN 7 MESSY DIAGRAMS
64. © Fraunhofer IESE 70 Anti Pattern 7: Messy Diagrams Huh?
65. © 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
66. © 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
67. © 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
68. © 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
69. © Fraunhofer IESE 75 CONCLUSION
70. © 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
71. © 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