Contents
Foreword to the Second Edition
Prologue: Software Architectures and Documentation
The prologue establishes the necessary concepts and vocabulary for the remainder of the book. It discusses how software architecture documentation is used and why it is important. It defines the concepts that provide the foundation of the book’s approach to documentation. It also contains seven basic rules for sound documentation.
P.1 A Short Overview of Software Architecture
P.1.2 Architecture and Quality Attributes
Coming to Terms: What Is Software Architecture?
Perspectives: What’s the Difference Between Architecture and Design?
P.2 A Short Overview of Architecture Documentation
P.2.1 Why Document Software Architecture?
Coming to Terms: Specification, Representation, Description, Documentation
P.2.2 Uses and Audiences for Architecture Documentation
P.2.3 Architecture Documentation and Quality Attributes
P.2.4 Economics of Architecture Documentation
P.2.5 The Views and Beyond “Method”
P.2.6 Views and Beyond in an Agile Environment
P.2.7 Architectures That Change Faster Than You Can Document Them
Coming to Terms: A Short History of Architecture Views
P.4.1 Three Categories of Styles
Coming to Terms: Module, Component
Coming to Terms: “Architecture Style” and “Architecture Pattern”
P.5 Seven Rules for Sound Documentation
Perspectives: Beware Notations Everyone “Just Knows”
Perspectives: Quivering at Arrows
Part I A Collection of Software Architecture Styles
Part I introduces the basic tools for software architecture documentation: architecture styles. A style is a specialization of element and relationship types, together with constraints on how they may be used. By identifying element and relationship types, styles identify the architecture structures that architects design to achieve the system’s quality and behavioral goals. There are three fundamental kinds of structures: module structures, component-and-connector structures, and allocation structures. Within each category reside a number of architecture styles. The introduction to Part I includes a brief catalog of the styles that are described in Chapters 1–5.
I.1 Three Categories of Styles
I.2 Style Guides: A Standard Organization for Explaining a Style
I.3 Choosing Which Element and Relation Properties to Document
I.4 Notations for Architecture Views
A module is an implementation unit of software that provides a coherent unit of functionality. Modules form the basis of many standard architecture views. This chapter defines modules and outlines the information required for documenting module views.
1.2 Elements, Relations, and Properties of Module Views
1.4 Notations for Module Views
1.4.2 Unified Modeling Language
1.4.3 Dependency Structure Matrix
1.4.4 Entity-Relationship Diagram
Chapter 2 A Tour of Some Module Styles
This chapter introduces some common and important styles in the module category. Each style is presented in terms of how it specializes the overall elements and relations found in module styles.
2.1.2 Elements, Relations, and Properties
2.1.3 What the Decomposition Style Is For
2.1.4 Notations for the Decomposition Style
2.1.5 Relation to Other Styles
2.1.6 Examples Using the Decomposition Style
2.2.2 Elements, Relations, and Properties
2.2.3 What the Uses Style Is For
2.2.4 Notations for the Uses Style
2.2.5 Relation to Other Styles
2.2.6 Examples Showing the Uses Style
2.3.2 Elements, Relations, and Properties
2.3.3 What the Generalization Style Is For
2.3.4 Notations for the Generalization Style
2.3.5 Relation to Other Styles
2.3.6 Examples Using the Generalization Style
2.4.2 Elements, Relations, and Properties
2.4.3 What the Layered Style Is For
2.4.4 Notations for the Layered Style
2.4.5 Relation to Other Styles
2.4.6 Examples Using the Layered Style
Coming to Terms: Virtual Machines
Perspectives: Calling Higher Layers
Perspectives: Using a DSM to Maintain a Layered Architecture
2.5.2 Elements, Relations, and Properties
2.5.3 What the Aspects Style Is For
2.5.4 Notations for the Aspects Style
2.5.5 Relation to Other Styles
2.5.6 Examples Using the Aspects Style
Coming to Terms: Aspect-Oriented Programming
2.6.2 Elements, Relations, and Properties
2.6.3 What the Data Model Is For
2.6.4 Notations for the Data Model Style
2.6.5 Relations to Other Styles
Chapter 3 Component-and-Connector Views
Component-and-connector views represent units of execution plus the pathways and protocols of their interaction. This chapter defines components and connectors and describes the rules for documenting them.
3.2 Elements, Relations, and Properties of C&C Views
3.2.2 Component-and-Connector Types and Instances
Perspectives: Are Complex Connectors Necessary?
Perspectives: Choosing Connector Abstractions
3.4.3 Semiformal Notations: UML
Perspectives: Data Flow and Control Flow Models
3.5 Relation to Other Kinds of Views
Chapter 4 A Tour of Some Component-and-Connector Styles
This chapter introduces some important component-and-connector (C&C) styles. The chapter describes how each style is a specialization of the generic elements and relations of C&C styles, discusses what makes each style useful, and explains how each style is documented.
4.1 An Introduction to C&C Styles
4.3.3 Service-Oriented Architecture Style
4.6 Crosscutting Issues for C&C Styles
4.6.3 Dynamic Creation and Destruction
Chapter 5 Allocation Views and a Tour of Some Allocation Styles
Software architects are often obliged to document nonsoftware structures and show how the software designs are mapped to the structures: the computing environment in which their software will run, the organizational environment in which it will be developed, and so on. This chapter introduces the allocation view category, which is used to express the allocation of software elements to nonsoftware structures, and three major allocation styles.
5.2.2 Elements, Relations, and Properties
5.2.3 What the Deployment Style Is For
5.2.4 Notation for the Deployment Style
5.2.5 Relation to Other Styles
5.3.2 Elements, Relations, and Properties
5.3.3 What the Install Style Is For
5.3.4 Notations for the Install Style
5.3.5 Relation to Other Styles
5.4.2 Elements, Relations, and Properties
5.4.3 What a Work Assignment Style Is For
5.4.4 Notations for the Work Assignment Style
5.4.5 Relation to Other Styles
Perspectives: Why Is a Work Assignment View Architectural?
Perspectives: Coordination Views
Part II Beyond Structure: Completing the Documentation
Part II concentrates on the rest of the information an architect should include in architecture documentation, such as context diagrams, variation points, interfaces, and software behavior.
This chapter introduces documentation approaches to handle some special architecture issues and situations, such as breaking a view into chunks, documenting context and variation points, and combining views.
6.1.1 Decomposition Refinement
6.1.2 Implementation Refinement
6.3 Documenting Context Diagrams
6.3.1 Create Context Diagrams Using the Vocabulary of the View
6.3.2 Content of a Context Diagram
6.3.3 Context Diagrams and Other Supporting Documentation
6.3.4 Notations for Context Diagrams
6.4 Documenting Variation Points
6.4.1 What Are Variation Points?
Coming to Terms: Product-Line Architectures
6.4.3 Dynamism and Dynamic Architectures
6.4.4 Documenting Variation Points
6.5 Documenting Architectural Decisions
6.5.1 Why Document Architectural Decisions?
6.5.2 A Template for Documenting Architectural Decisions
6.5.3 Documenting Alternatives
6.5.4 Which Decisions to Document
6.5.5 The Payback for Documenting Architectural Decisions
Perspectives: From Documenting Architectures to Architecting As Decision Making
Perspectives: An Ontology of Architecture Decisions
6.6.1 Types of Associations Between Views
6.6.4 Examples of Combined Views
Chapter 7 Documenting Software Interfaces
The interfaces of the elements are critical parts of any architecture, and documenting them is an important responsibility for the architect. This chapter tells you how to specify an interface.
Coming to Terms: Provided vs. Required Interfaces
7.2.1 Showing the Existence of Interfaces in Diagrams
7.3 A Standard Organization for Interface Documentation
Coming to Terms: Error Handling
7.4 Stakeholders of Interface Documentation
7.5 Conveying Syntactic Information
7.6 Conveying Semantic Information
Coming to Terms: Signature, Interface, API
7.7 Examples of Interface Documentation
7.7.2 Interface to a SOAP Web Service
Chapter 8 Documenting Behavior
Documenting behavior is an essential counterpoint to documenting structure. This chapter covers the techniques and notations available for expressing the behavior of elements, groups of elements, and the system as a whole.
8.2.1 Step 1: Decide What Kinds of Questions You Need to Answer
8.2.2 Step 2: Determine What Types of Information Are Available or Can Be Constrained
8.2.3 Step 3: Choose a Notation
8.3 Notations for Documenting Behavior
8.3.1 Notations for Capturing Traces
8.3.2 Notations for Capturing Comprehensive Models
8.4 Where to Document Behavior
8.5.1 Driving Development Activities
Part III Building the Architecture Documentation
Part III covers what you have to do to create and maintain the documentation artifacts: choosing views to include, laying out and packaging the information, and reviewing the document.
This chapter provides guidance for selecting views, given the intended use of an architecture: analysis, reconstruction, achieving common understanding, the basis for deriving code, and so on.
9.1 Stakeholders and Their Documentation Needs
9.2 A Method for Choosing the Views
Perspectives: Listening to the Stakeholders
Perspectives: How Not to Introduce an Architecture
Chapter 10 Building the Documentation Package
This chapter explains how the documentation is organized to serve its stakeholders. The chapter shows how the elements discussed in the prior chapters fit together to produce usable documentation. The chapter includes templates for architecture documentation.
10.1.1 A Standard Organization for Documenting a View
Perspectives: From Context Diagrams to a Context View
10.1.2 Useful Variations in the Standard Organization for a View
10.1.3 Avoiding Unnecessary Repetition Across Views or View Packets
10.2 Documentation Beyond Views
10.2.1 A Standard Organization for Documenting Information Beyond Views
10.2.2 Useful Variations in the Standard Organization for Documentation Beyond Views
10.3 Documenting a Mapping to Requirements
Perspectives: A Mapping to Requirements: You Might Already Have It
10.4 Packaging the Architecture Documentation
10.4.2 Online Documentation, Hypertext, and Wikis
10.4.3 Configuration Management
10.4.4 Follow a Release Strategy
Perspectives: Presentation Is Also Important
Perspectives: Tooling Requirements
Chapter 11 Reviewing an Architecture Document
This chapter describes a step-by-step approach for conducting a structured review of an architecture document, and it includes a large selection of review questions.
Coming to Terms: Active Design Reviews
11.2 Sample Question Sets for Reviewing the Architecture Document
11.2.1 Example Question Set for Capturing the Right Stakeholders and Concerns
11.2.2 Example Question Set for Supporting Evaluation
11.2.3 Example Question Set for Supporting Development
11.2.4 Example Question Set for Reviewing for Conformance to ISO/IEC 42010
11.3 An Example of Constructing and Conducting a Review
Epilogue: Using Views and Beyond with Other Approaches
The epilogue compares the “Views and Beyond” approach to other documentation approaches. It ties related work to the prescriptions given in this book.
E.1 ISO/IEC 42010, née ANSI/IEEE Std 1471-2000
E.1.2 42010 and Views and Beyond
E.2 Rational Unified Process/Kruchten 4+1
E.2.1 RUP/4+1 and Views and Beyond
E.3 Using the Rozanski and Woods Viewpoint Set
Coming to Terms: Architecture Perspectives
E.3.1 Rozanski and Woods Viewpoints and Views and Beyond
E.4 Documenting Architecture in an Agile Development Project
E.4.2 Agile Development and Views and Beyond
E.5 U.S. Department of Defense Architecture Framework
E.5.2 DoDAF and Software Architecture
E.5.3 DoDAF and Views and Beyond
E.5.4 A Strategy to Use DoDAF to Document Software Architecture
E.6 Where Architecture Documentation Ends
Appendix A UML—Unified Modeling Language
This appendix gives an overview of the Unified Modeling Language and tells how it should be used to document the architecture constructs described in this book.
Perspectives: UML Class Diagrams: Too Much, Too Little
A.3 Documenting a Component-and-Connector View
A.4 Documenting an Allocation View
A.4.2 Install and Implementation Styles
A.5.5 Interaction Overview Diagram
Appendix B SysML—Systems Modeling Language
The Systems Modeling Language (SysML) is a general-purpose systems modeling language intended to support a broad range of analysis and design activities for systems engineering applications. This appendix gives a short overview of using SysML to represent an architecture.
B.1 Architecture Documentation
B.4 Documenting a Component-and-Connector View
B.5 Documenting an Allocation View
Appendix C AADL—The SAE Architecture Analysis and Design Language
The Architecture Analysis and Design Language (AADL) provides a textual and graphical language to represent the runtime architecture of software systems as a component-based model in terms of tasks and their interactions, the hardware platform on which the system executes, and the physical environment with which it interfaces. This appendix summarizes AADL and briefly describes how it can be used to document architectures.
C.2 Documenting a Module Style
C.3 Documenting a Component-and-Connector View