Main Page

Documenting Software Architectures: Views and Beyond
By Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord, Judith Stafford
Publisher : Addison Wesley
Pub Date : September 27, 2002
ISBN : 0-201-70372-6
Pages : 560

"This book is of immense value. It should save you months of trials and errors, lots of undeserved hassle, and many costly mistakes that could potentially jeopardize the whole endeavor. It will become an important reference on the shelf of the software architect."—From the Foreword by Philippe Kruchten, Rational Software Canada

"There is probably no better set of authors to write this book. The material is readable. It uses humor effectively. It is nicely introspective when appropriate, and yet in the end it is forthright and decisive....This is a tour de force on the subject of architectural documentation."—Robert Glass, Editor-in-Chief, Journal of Systems and Software and Editor/Publisher, The Software Practitioner

For all but the most trivial software systems, you must pay close attention to the architecture—the conceptual glue that holds every phase of a project together for its many stakeholders. Without an architecture that is appropriate for the problem being solved, the project will stumble along or, most likely, fail. Even with a superb architecture, if that architecture is not well understood or well communicated—in other words, well documented—the project cannot be considered a complete success.

Although architecture is now widely recognized as a critical element in software development, there has been little guidance independent of language or notation on how to capture it. Based on the authors' extensive experience, Documenting Software Architectures helps you decide what information to document, and then, with guidelines and examples (in various notations, including UML), shows you how to express an architecture in a form that everyone can understand. If you go to the trouble of creating a strong architecture, you must also be prepared to describe it thoroughly and clearly, and to organize it so that others can quickly find the information they need.

Essential topics for practitioners include:

  • Seven rules for sound documentation

  • The uses of software architecture documentation, including goals and strategies

  • Architectural views and styles, with general introductions and specific examples

  • Documenting software interfaces and software behavior

  • Templates for capturing and organizing information to generate a coherent package

•  Table of Contents
Documenting Software Architectures: Views and Beyond
By Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord, Judith Stafford
Publisher : Addison Wesley
Pub Date : September 27, 2002
ISBN : 0-201-70372-6
Pages : 560
    In praise of Documenting Software Architectures
    About the Cover
    Reader's Guide
      Contents and Organization
      Stylistic Conventions
      How to Read and Use This Book
      Commercial Tools and Notations
    Prologue Software Architectures and Documentation
      Section P.1.  The Role of Architecture
      Section P.2.  Uses of Architecture Documentation
      Section P.3.  Interfaces
      Section P.4.  Views
      Section P.5.  Viewtypes and Styles
      Section P.6.  Seven Rules for Sound Documentation
      Section P.7.  Summary Checklist
      Section P.8.  Discussion Questions
      Section P.9.  For Further Reading
    Part I.  Software Architecture Viewtypes and Styles
      Chapter 1.  The Module Viewtype
      Section 1.1.  Overview
      Section 1.2.  Elements, Relations, and Properties of the Module Viewtype
      Section 1.3.  What the Module Viewtype Is For and What It's Not For
      Section 1.4.  Notations for the Module Viewtype
      Section 1.5.  Relation to Other Viewtypes
      Section 1.6.  Summary Checklist
      Section 1.7.  Discussion Questions
      Section 1.8.  For Further Reading
      Chapter 2.  Styles of the Module Viewtype
      Section 2.1.  Decomposition Style
      Section 2.2.  Uses Style
      Section 2.3.  Generalization Style
      Section 2.4.  Layered Style
      Section 2.5.  Summary Checklist
      Section 2.6.  Discussion Questions
      Section 2.7.  For Further Reading
      Chapter 3.  The Component-and-Connector Viewtype
      Section 3.1.  Overview
      Section 3.2.  Elements, Relations, and Properties of the C&C Viewtype
      Section 3.3.  What the C&C Viewtype Is For and What It's Not For
      Section 3.4.  Notations for the C&C Viewtype
      Section 3.5.  Relation to Other Viewtypes
      Section 3.6.  Summary Checklist
      Section 3.7.  Discussion Questions
      Section 3.8.  For Further Reading
      Chapter 4.  Styles of the Component-and-Connector Viewtype
      Section 4.1.  The Pipe-and-Filter Style
      Section 4.2.  Shared-Data Style
      Section 4.3.  Publish-Subscribe Style
      Section 4.4.  Client-Server Style
      Section 4.5.  Peer-to-Peer Style
      Section 4.6.  Communicating-Processes Style
      Section 4.7.  Notations for C&C Styles
      Section 4.8.  Summary Checklist
      Section 4.9.  Discussion Questions
      Section 4.10.  For Further Reading
      Chapter 5.  The Allocation Viewtype and Styles
      Section 5.1.  Overview
      Section 5.2.  Elements, Relations, and Properties of the Allocation Viewtype
      Section 5.3.  Deployment Style
      Section 5.4.  Implementation Style
      Section 5.5.  Work Assignment Style
      Section 5.6.  Summary Checklist
      Section 5.7.  Discussion Questions
      Section 5.8.  For Further Reading
    Part II.  Software Architecture Documentation in Practice
      Chapter 6.  Advanced Concepts
      Section 6.1.  Chunking Information: View Packets, Refinement, and Descriptive Completeness
      Section 6.2.  Using Context Diagrams
      Section 6.3.  Combined Views
      Section 6.4.  Documenting Variability and Dynamism
      Section 6.5.  Creating and Documenting a New Style
      Section 6.6.  Summary Checklist
      Section 6.7.  Discussion Questions
      Section 6.8.  For Further Reading
      Chapter 7.  Documenting Software Interfaces
      Section 7.1.  Overview
      Section 7.2.  Interface Specifications
      Section 7.3.  A Standard Organization for Interface Documentation
      Section 7.4.  Stakeholders of Interface Documentation
      Section 7.5.  Notation for Interface Documentation
      Section 7.6.  Examples of Interface Documentation
      Section 7.7.  Summary Checklist
      Section 7.8.  Discussion Questions
      Section 7.9.  For Further Reading
      Chapter 8.  Documenting Behavior
      Section 8.1.  Beyond Structure
      Section 8.2.  Where to Document Behavior
      Section 8.3.  Why to Document Behavior
      Section 8.4.  What to Document
      Section 8.5.  How to Document Behavior: Notations and Languages
      Section 8.6.  Summary Checklist
      Section 8.7.  Discussion Questions
      Section 8.8.  For Further Reading
      Chapter 9.  Choosing the Views
      Section 9.1.  Stakeholders and Their Documentation Needs
      Section 9.2.  Making the Choice
      Section 9.3.  Two Examples
      Section 9.4.  Summary Checklist
      Section 9.5.  Discussion Questions
      Section 9.6.  For Further Reading
      Chapter 10.  Building the Documentation Package
      Section 10.1.  One Document or Several?
      Section 10.2.  Documenting a View
      Section 10.3.  Documentation Beyond Views
      Section 10.4.  Validating Software Architecture Documentation
      Section 10.5.  Summary Checklist
      Section 10.6.  Discussion Questions
      Section 10.7.  For Further Reading
      Chapter 11.  Other Views and Beyond
      Section 11.1.  Overview
      Section 11.2.  Rational Unified Process/Kruchten 4+1
      Section 11.3.  UML
      Section 11.4.  Siemens Four Views
      Section 11.5.  C4ISR Architecture Framework
      Section 11.6.  ANSI/IEEE-1471-2000
      Section 11.7.  Data Flow and Control Flow
      Section 11.8.  RM-ODP
      Section 11.9.  Where Architecture Documentation Ends
      Section 11.10.  A Final Word
      Section 11.11.  For Further Reading
      Appendix A.  Excerpts from a Software Architecture Documentation Package
      Volume I: ECS Software Architecture Documentation Beyond Views
      Volume I ECS Software Architecture Documentation Beyond Views
      Chapter 1 ECS Architecture Documentation Roadmap
      Chapter 2 ECS System Overview
      Chapter 3 ECS Software Architecture View Template
      Chapter 4 Mapping Between Views
      Chapter 5 Directory
      Chapter 6 Architecture Glossary and Acronym List
      Chapter 7 Rationale, Background, and Design Constraints
      Volume II: ECS Software Architecture Views
      Volume II ECS Software Architecture Views
      Chapter 1 Module Decomposition View
      Chapter 2 Module Uses View
      Chapter 3 Module Generalization View
      Chapter 4 Module Layered View
      Chapter 5 C&C Pipe-and-Filter View
      Chapter 6 C&C Shared-Data View
      Chapter 7 C&C Communicating-Processes View
      Chapter 8 Allocation Deployment View
      Chapter 9 Allocation Implementation View
      Chapter 10 Allocation Work Assignment View