Upgrade to Pro — share decks privately, control downloads, hide ads and more …

SEACON 2022 - Meisterwerk oder Groschenroman - ...

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.

Matthias Naab

May 18, 2022
Tweet

More Decks by Matthias Naab

Other Decks in Technology

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 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)
  3. © Fraunhofer IESE 5 Some Basics System (Code + Infrastructure)

    Architecture Architecture Documentation has an describes
  4. © 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
  5. © Fraunhofer IESE 11 Motivation for this Talk We see

    great architectures much more often than great architecture documentation.
  6. © Fraunhofer IESE 12 Anti Pattern #: <Anti Pattern Name>

    ◼ <Description> ◼ <Example> ◼ <Impact> ◼ <Tips for Improvement>
  7. © Fraunhofer IESE 15 Anti Pattern 1: No Architecture Documentation

    Photo by Joan Gamell on Unsplash Code is the only Truth!
  8. © 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
  9. © Fraunhofer IESE 17 No Goal State: Intended Architecture vs

    Implemented Architecture System (Code + Infrastructure) Architecture Architecture Documentation has an describes
  10. © 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
  11. © Fraunhofer IESE 19 No Goal State: Impact Photo by

    John Schnobrich on Unsplash I can always explain the concept!
  12. © 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
  13. © 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
  14. © 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.
  15. © 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
  16. © Fraunhofer IESE 27 Anti Pattern 2: Architecture Documentation as

    Deliverable Photo by Alvaro Reyes on Unsplash TODO: Document the architecture
  17. © 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.”
  18. © Fraunhofer IESE 30 Anti Pattern 2: Architecture Documentation as

    Deliverable – Description Reverse Engineering Tool System Artifacts Architecture Model Architecture Documentation
  19. © 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.
  20. © 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
  21. © 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
  22. © Fraunhofer IESE 35 Anti Pattern 3: No RT/DT-Differentiation Photo

    by Flo Karr & Christina @ wocintechchat.com on Unsplash What’s the difference?
  23. © 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
  24. © Fraunhofer IESE 38 Runtime and Devtime Entities might be

    the same … Runtime Devtime IDE System Chat Event Processor Chat Event Processor
  25. © 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
  26. © 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
  27. © 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
  28. © 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.
  29. © 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
  30. © 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/
  31. © 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!)
  32. © 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?
  33. © 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
  34. © 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
  35. © 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
  36. © Fraunhofer IESE 57 Anti Pattern 5: Lacking Connection to

    Code Between two worlds Photo by Alex Radelich on Unsplash
  37. © 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
  38. © 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
  39. © 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
  40. © 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
  41. © Fraunhofer IESE 63 Anti Pattern 6: Over-Focused on Templates

    and Views Focus on templates instead of readers
  42. © 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, …
  43. © 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
  44. © 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
  45. © 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
  46. © 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
  47. © 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
  48. © 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
  49. © 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
  50. © 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
  51. © 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