Chapter 22: Documenting Architectures – Views & Behavior

Producing high-quality software necessitates meticulous architectural documentation, which serves as an essential communication mechanism among diverse project stakeholders, including developers, testers, project managers, and future maintainers, while also functioning as a critical repository for complex design decisions and rationale. Since software architecture is a multidimensional entity, documentation relies on various specialized representations called views, each focusing on a subset of system elements and relations relevant to specific goals or quality attributes. The primary structural views are categorized as Module Views, which describe the static decomposition of implementation units (such as classes or layers) necessary for coding blueprints and analyzing change impact; Component-and-Connector (C&C) Views, which illustrate the runtime presence of elements and their pathways of interaction (connectors), crucial for reasoning about operational qualities like performance and availability; and Allocation Views, which map software units to environmental elements such as hardware, processors, or development teams. Furthermore, specialized Quality Views (e.g., security or performance views) can be constructed by extracting relevant information across structures to address pervasive system concerns. To complement these structural descriptions, behavioral documentation, utilizing either trace-oriented notations like sequence diagrams and use cases, or comprehensive approaches like state machine diagrams, details how architectural elements interact over time. Beyond structural and behavioral views, a complete architecture description must include context diagrams, a glossary, variability guides, explicit mappings between views, and detailed design rationale, which lays out the justification for architectural choices, including risks and discarded alternatives. Notations utilized range from informal box-and-line sketches to semiformal standards like UML and SysML, or highly rigorous formal architecture description languages (ADLs). For dynamic systems that change rapidly, the documentation strategy must shift to capturing essential invariants and the allowed mechanisms of change, often supported by automatically generated interface descriptions, ensuring that the documentation remains a reliable source of truth.