Documenting Software Architectures: Views and Beyond

Architecture is crucial to the success of any large software system -- but even a superb architecture will fail if it isn't communicated well. Now, there's a language- and notation-independent guide to capturing architecture so it can be used successfully by every analyst, software designer, and developer. The authors review the diverse goals and uses of software architecture documentation, providing documentation strategies for several common scenarios. They identify the basic unit of software architecture documentation: the viewtype, which specifies the type of information to be provided in an architectural view. For each viewtype -- Modules, Component-and-Connectors, and Allocation -- they offer detailed guidance on documenting what really matters. Next, they demonstrate how to package architecture documentation in coherent, usable form: augmenting architectural views with documentation of interfaces and behavior; accounting for architectural variability and dynamic systems; and more.

Table of Contents:
About the Cover. Foreword. Preface. Acknowledgments. Reader's Guide. Prologue: Software Architectures and Documentation. The Role of Architecture. Coming to Terms: Software Architecture. Perspectives: What's the Difference Between Architecture and Design? Coming to Terms: Documentation, Description, Representation, Specification. Uses of Architecture Documentation. Interfaces. Views. Coming to Terms: Architectural Views. Viewtypes and Styles. Viewtypes. Styles. Summary: Viewtypes, Styles, and Views. Coming to Terms: Module, Component. Seven Rules for Sound Documentation. Rule 1: Write Documentation from the Reader's Point of View. Rule 2: Avoid Unnecessary Repetition. Rule 3: Avoid Ambiguity. Rule 4: Use a Standard Organization. Rule 5: Record Rationale. Rule 6: Keep Documentation Current But Not Too Current. Rule 7: Review Documentation for Fitness of Purpose. Perspectives: Quivering at Arrows. Summary Checklist. Discussion Questions. For Further Reading. I. SOFTWARE ARCHITECTURE VIEWTYPES AND STYLES. Viewtypes and Style Catalog. Module Viewtype. Component-and-Connector Viewtype. Allocation Viewtype. Style Guides: A Standard Organization for Documenting a Style. 1. The Module Viewtype. Overview. Elements, Relations, and Properties of the Module Viewtype. Elements. Relations. Properties. Coming to Terms: Substitutability. What the Module Viewtype Is For and What It's Not For. Notations for the Module Viewtype. Informal Notations. UML. Relation to Other Viewtypes. Summary Checklist. Discussion Questions. For Further Reading. 2. Styles of the Module Viewtype. Decomposition Style. Overview. Elements, Relations, and Properties. What the Decomposition Style Is For and What It's Not For. Notations for the Decomposition Style. Relation to Other Styles. Examples of the Decomposition Style. Coming to Terms: Subsystem 622.2 Uses Style. Overview. Elements, Relations, and Properties. What the Uses Style Is For and What It's Not For. Notations for the Uses Style. Relation to Other Styles. Example of the Uses Style. Coming to Terms: Uses 682.3 Generalization Style. Overview. Elements, Relations, and Properties. What the Generalization Style Is For and What It's Not For. Notations for the Generalization Style. Relation to Other Styles. Coming to Terms: Generalization. Examples of the Generalization Style. Layered Style. Overview. Elements, Relations, and Properties. What the Layered Style Is For and What It's Not For. Notations for the Layered Style. Relation to Other Styles. Examples of the Layered Style. Coming to Terms: Virtual Machines. Perspectives: Upwardly Mobile Software. Perspectives: Levels of Distraction. Perspectives: UML Class Diagrams: Too Much, Too Little. Summary Checklist. Discussion Questions. For Further Reading. 3 The Component-and-Connector Viewtype. Overview. Elements, Relations, and Properties of the C&C Viewtype. Elements. Relations. Properties. Perspectives: Are Connectors Necessary? Perspectives: Choosing Connector Abstractions. What the C&C Viewtype Is For and What It's Not For. Perspectives: Data Flow and Control Flow Projections. Notations for the C&C Viewtype. Relation to Other Viewtypes. Summary Checklist. Discussion Questions. For Further Reading. 4. Styles of the Component-and-Connector Viewtype. The Pipe-and-Filter Style. Overview. Elements, Relations, and Properties. What the Pipe-and-Filter Style Is For and What It's Not For. Relation to Other Styles. Examples of the Pipe-and-Filter Style. Shared-Data Style. Overview. Elements, Relations, and Properties. What the Shared-Data Style Is For and What It's Not For. Relation to Other Styles. Example of the Shared-Data Style. Publish-Subscribe Style. Overview. Elements, Relations, and Properties. What the Publish-Subscribe Style Is For and What It's Not For. Relation to Other Styles. Examples of the Publish-Subscribe Style. Client-Server Style. Overview. Elements, Relations, and Properties. What the Client-Server Style Is For and What It's Not For. Relation to Other Styles. Examples of the Client-Server Style. Peer-to-Peer Style. Overview. Elements, Relations, and Properties. What the Peer-to-Peer Style Is For and What It's Not For. Relation to Other Styles. Examples of the Peer-to-Peer Style. Communicating-Processes Style. Overview. Elements, Relations, and Properties. What the Communicating-Processes Style Is For and What It's Not For. Relation to Other Styles. Examples of the Communicating-Processes Style. Notations for C&C Styles. Informal Notations. Formal Notations. Perspectives: Using Classes to Represent Component Types and Instances. Coming to Terms: Components Versus UML Components. Summary Checklist. Discussion Questions. For Further Reading. 5. The Allocation Viewtype and Styles. Overview. Elements, Relations, and Properties of the Allocation Viewtype. Deployment Style. Overview. Elements, Relations, and Properties. What the Deployment Style Is For and What It's Not For. Notation for the Deployment Style. Relation to Other Styles. Examples of the Deployment Style. Implementation Style. Overview. Elements, Relations, and Properties. What the Implementation Style Is For and What It's Not For. Notation for the Implementation Style. Relation to Other Styles. Example of the Implementation Style. Work Assignment Style. Elements, Relations, and Properties. What the Work Assignment Style Is For and What It's Not For. Notations for the Work Assignment Style. Relation to Other Styles. Example of the Work Assignment Style. Summary Checklist. Discussion Questions. For Further Reading. II. SOFTWARE ARCHITECTURE DOCUMENTATION IN PRACTICE. 6. Advanced Concepts. Chunking Information: View Packets, Refinement, and Descriptive Completeness. View Packets. Refinement. Descriptive Completeness. Using Context Diagrams. Top-Level Context Diagrams. Content of a Context Diagram. Context Diagrams and Other Supporting Documentation. Notations for Context Diagrams. Example of a Context Diagram. Combined Views. When to Combine Views. Types of Mapping. Elements, Relations, and Properties. Documenting Combined Views. Examples of Combined Views. Other Examples. Documenting Variability and Dynamism. Variability. Dynamism. Recording the Information. Notations for Variability and Dynamism. Perspectives: What Time Is It? Creating and Documenting a New Style. Coming to Terms: Styles, Patterns. Summary Checklist. Discussion Questions. For Further Reading. 7. Documenting Software Interfaces. Overview. Interface Specifications. A Standard Organization for Interface Documentation. Coming to Terms: Exceptions and Error Handling. Stakeholders of Interface Documentation. Notation for Interface Documentation. Showing the Existence of Interfaces. Conveying Syntactic Information. Conveying Semantic Information. Summary. Perspectives: Multiple Interfaces. Coming to Terms: Signature, Interface, API. Examples of Interface Documentation. SCR-Style Interface. IDL. Custom Notation. XML. Summary Checklist. Discussion Questions. For Further Reading. 8. Documenting Behavior. Beyond Structure. Where to Document Behavior. Why to Document Behavior. System Analysis. Driving Development Activities. What to Document. Types of Communication. Constraints on Ordering. Clock-Triggered Stimulation. How to Document Behavior: Notations and Languages. Traces. Static Models. Summary Checklist. Discussion Questions. For Further Reading. 9. Choosing the Views. Stakeholders and Their Documentation Needs. Perspectives: Architecture Trade-off Analysis Method. Making the Choice. Two Examples. A Small Project: A-7E. A Large Project: ECS. Summary Checklist. Discussion Questions. For Further Reading. 10. Building the Documentation Package. One Document or Several? Perspectives: What the Meaning of “Is” Is. Documenting a View. Perspectives: Presentation Is Also Important. Documentation Beyond Views. How the Documentation Is Organized to Serve a Stakeholder. What the Architecture Is. Why the Architecture Is the Way It Is: Background, Design Constraints, and Rationale. Perspectives: Global Analysis. Validating Software Architecture Documentation. Perspectives: A Glossary Would Have Helped. Summary Checklist. Discussion Questions. For Further Reading. 11. Other Views and Beyond. Overview. Rational Unified Process/Kruchten 4+1. UML. Class and Object Diagrams. Component Diagrams. Deployment Diagrams. Behavioral Diagrams. Siemens Four Views. Global Analysis. Conceptual Architecture View. Module Architecture View. Execution Architecture View. Code Architecture View. Summary. C4ISR Architecture Framework. Common Architectural Views of the C4ISR Framework. Common Products. ANSI/IEEE-1471-2000. Data Flow and Control Flow. Data Flow Views. Control Flow Views. Perspectives: You're All Just Guessing! RM-ODP. Where Architecture Documentation Ends. Architecture Description Languages. Commercial Components. Hypertext Documentation. Configuration Management. A Final Word. For Further Reading. Appendix A: Excerpts from a Software Architecture Documentation Package. Volume I: ECS Software Architecture Documentation Beyond Views. Volume II: ECS Software Architecture Views. Glossary. References. Index. 0201703726T08302002