Documenting Software Architectures: Views and Beyond

Description

• Copyright 2003
• Dimensions: 6-1/4" x 9-1/4"
• Pages: 560
• Edition: 1st

• Book
• ISBN-10: 0-201-70372-6
• ISBN-13: 978-0-201-70372-6

"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

0201703726B08222002



Downloads

Supplements

Audience

This book was written primarily for software architects and technical writers who are charged with producing architectural documentation for software projects. However, it was also written keeping in mind those who digest and use that documentation. A software architect can provide this book as a companion to his or her documentation, pointing consumers to specific sections that explain documentation organizing principles, notations, concepts, or conventions.

We assume basic familiarity with the concepts of software architecture, but also provide pointers to sources of information to fill in the background. In many cases, we will sharpen and solidify basic concepts that you already may be familiar with: architectural views, architectural styles, and interfaces are all cases in point.

Contents and Organization

The book is organized into two parts with a prologue.

Prologue. This section provides the necessary concepts and vocabulary for Part I.

Part I: Software Architecture Viewtypes. This part introduces the basic tools for software architecture documentation: the viewtypes. A viewtype is a specification of the kind of information to be provided in a view. There are three basic viewtypes (Modules, Component-and-Connectors, and Allocation). Within each viewtype reside a number of architectural styles, or specializations of the viewtype.

• Chapter 1: The Module Viewtype. A module is an implementation unit of software that provides a coherent unit of functionality. Modules form the basis of many standard architectural views. This chapter defines modules, and outlines the information required for documenting views whose elements are modules.
• Chapter 2: Styles of the Module Viewtype. This chapter introduces the prevalent styles in the module viewtype: decomposition, uses, generalization (the style that includes object-based inheritance), and layers. Each style is presented in terms of how it specializes the overall module viewtype's elements and relations.
• Chapter 3: The Component and Connector Viewtype. Components and connectors are used to describe the runtime structure(s) of a software system, and they can exist in many forms: processes, objects, clients, servers, and data stores. Component-and-connector models include as elements the pathways of interaction, such as communication links and protocols, information flows, and access to shared storage. Often these interactions will be carried out using complex infrastructure, such as middleware frameworks, distributed communication channels, and process schedulers. This chapter introduces components and connectors, and rules for documenting them.
• Chapter 4: Styles of the Component and Connector Viewtype. This chapter introduces the major styles of the component and connector viewtype, including communicating processes, pipe and filter, client-server, peer to peer, shared data, and publish-subscribe. For each, it describes how the style is a specialization of the generic elements and relations of the viewtype, what the style is useful for, and how it is documented.
• Chapter 5: The Allocation Viewtype and Styles. Software architects are often obliged to document nonarchitectural structures and show how their software designs are mapped to them: the computing environment in which their software will run, the organizational environment in which it will be developed, etc. This chapter introduces the allocation viewtype, which is used to express the allocation of software elements to nonsoftware structures and the three major styles of the allocation viewtype: the deployment style, which allocates software to hardware processing and communication units; the implementation style, which allocations software units to a configuration structure; and the work assignment style, which allocates software units to development teams in an organizational structure.

Part II: Software Architecture Documentation in Practice. This part concentrates on the complete package of architecture documentation that is incumbent on a good architect to produce. It completes the picture painted by the first two parts.

• Chapter 6: Advanced Concepts. This chapter discusses both concepts that cut across viewtypes and those that are more advanced in nature. These concepts are:
    - Information chunking and refinement
    - Context diagrams
    - Combining views
    - Expressing variability of the architecture within the documentation such as for product lines
    - Expressing the architecture of dynamic systems that change their basic structure while they are running.
    - Creating and documenting new styles
• Chapter 7: Documenting a Software Interface. A critical part of any architecture is the interfaces of the elements, and documenting those interfaces is an important part of the architect's overall documentation obligation. This chapter establishes the information needed to adequately specify an interface, and explores the issues associated with doing so.
• Chapter 8: Documenting Behavior. This chapter covers the techniques and notations available for expressing the behavior of components and the emergent system as it runs.
• Chapter 9: Choosing the Views. This chapter provides guidance for the selection of views, given the intended usage of an architecture (analysis, reconstruction, achieving common understanding, basis for deriving code, etc.)
• Chapter 10: Building the documentation package. This chapter describes how the documentationis organized to serve a stakeholder. How do the various elements discussed in the prior chpaters fit together in order to produce useable documentation.
• Chapter 11: Related Work. This chapter ties related work to the prescriptions given in this book. It maps the 4+1 view model of architecture (created by Kruchten and embraced as part of the Rational Unified Process) to the views and documentation conventions prescribed in this book. It does the same for the Siemens Four Views model of Soni, Nord, and Hofmeister; the U.S. Department of Defense's C4ISR model of architecture; some industrial architecture standards; and the recently approved IEEE standard for architecture documentation.
• Appendix A: Software architecture documentation package for ECS. An extended example of the NASA ECS system that demonstrates many of the concepts that we discuss in this book.

Stylistic conventions

Our metaphor for this book is that of a highway that takes you where you want to go quickly and efficiently. We have used the main flow of the text as our highway: If all you care about is how to document software architecture and are not interested in any background, related concepts, history, or other diversions, then you should just stay on the highway. But if you're not familiar with this "route," you might want to traverse it in a more leisurely fashion. In this book we use sidebars—visually distinguished diversions from the straight-line flow—to provide alternative routes through the book.

We have chosen a lay out for this book that places these diversions on the left hand pages while the main highway is on the right hand pages. This will allow you to either get straight to your destingation or meander as you wish. Our visual highway markers are the following.

Real highways have information signs that help you get to your destination. In this book, information signs include concise term definitions, such as this one:

DEFINITION: A view is a representation of a set of system elements and relationships among them.

They also include prescriptive advice or rules for architecture documentation, shown thus:

ADVICE: Every graphical presentation should include a key that explains the notation used.

Information signs can also point you to a source of more information:

FOR MORE INFORMTAION: Section 6.4, Documenting Variablity and Dinamism, discusses dynamic architectures.

Finally, if others have left their mark on a subject, we share their words like this:

A good notation should embody characteristics familiar to any user of mathematical notation: Ease of expressing constructs arising in problems, suggestivity, ability to subordinate detail, economy, amenability to formal proofs.
—Kenneth E. Iverson, "Notation as a Tool of Thought", from ACM Turing Award Lectures: The First Twenty Years (1966-1985), ACM Press Anthology Series, Addison-Wesley, 1987, pp. 338-387.

At the end of each chapter, you can find

• A summary checklist, highlighting the main points and prescriptive guidance of the chapter
• A "For Further Reading" section, offering references for more in-depth treatment of related topics
• A set of discussion questions that can serve as the basis for classroom or brown-bag-lunch-group conversation.

How to Read this Book; How to Use this Book

We distinguish between a first-time reader of this book, and someone who has already read it but now wishes to use it as a companion for documenting an architecture. We also identify a lightweight path for those documenting small systems.

A first-time reader should concentrate on

• The Prologue, to gain an appreciation for the necessity and uses of sound architecture documentation.
• The introduction to Part I, to gain an understanding of viewtypes, styles and views, and to get a glimpse of the three viewtypes and the myriad of styles discussed in this book.
• Sections 6.1, 6.2 and 6.3 to become familiar with the organizational scheme for documenting an architecture by means of views and documentation across views, as well as the foundational concepts important in documentation such as refinement, context diagrams, and rationale capture.
• Chapter 9, to learn how to to choose the important views.
• Chapter 10, to learn about what to include in a documentation package.

In addition, the first-time reader should

• Browse the viewtype chapters in Part I (Chapters 1-5) to gain an overview of the views that are possible to include in a documentation package.
• Read the remainder of Chapter 6, Advanced Concepts, to gain understanding about topics such as documenting variability and dynamism, combining views, and creating new styles.
• Lightly read Chapter 8 to learn about documenting the behavior (as opposed to the structure) of a software system and its architectural elements.
• Browse Chapter 11, Related Work, to see how other people have approached the problem of architecture documentation, and how the ideas in these book correspond.

A reader wishing to use the book as a companion in a documentation effort should consider this strategy:

• To refresh your memory about the organization and structure of an architecture documentation package, re-visit the Prologue and Sections 6.1-6.3.
• Use those two selections plus Chapter 9, Choosing the Views, as the basis for planning your documentation package. Let it help you match the stakeholders you have and the uses your documentation will support with the kind of information you need to provide.
• For each view you have elected to document, use the chapter in Part I in which that view is discussed.
• To make sure your documentation complies with other prescriptive methods such as Rational's 4+1 approach, consult Chapter 11, Related Work.

A reader seeking a lightweight approach to documentation should consider the strategy of reading those chapters that contain templates for documentation and then looking up those concepts that are unfamiliar. The chapters containing templates are Chapter 10: Building the documentation package and Chapter 7, Documenting a Software Interface.

Commercial Tools and Notations

Finally, a word about commercial tools and notations. There is no shortage of heavily-marketed tool suites available for capturing design information, especially in the realm of object-oriented systems. Some of these tools are bound up intimately with associated design methodologies and notational languages. Some are aimed at points in the design space other than architecture. If you have decided to adopt one of these tools and/or notations, how does the information in this book relate to you?

The answer is that we have explicitly tried to be language- and tool-independent. Rather than concentrate on the constraints imposed by a particular tool or notation, we have concentrated on the information you should capture about an architecture. We believe that is the approach you should take, too: Concentrate on the information you need to capture, and then figure out how to capture it using the tool you've chosen. Almost all tools provide ways to add free-form annotations to the building blocks they provide; these annotations will let you capture and record information in ways you see fit. Remember that not all of the people for whom architecture documentation is prepared will be able to use the tool environment you've chosen or understand the commercial notation you've adopted.

Having said that, however, we note that the Unified Modeling Language (UML) is a fact of life, and in many cases is the right choice for conveying architectural information. And so this book uses UML 1.4 in many, but not all, of its examples. We also show how to represent each concept we discuss using UML. We assume that the reader is familiar with the basic UML diagrams and symbology—our purpose is not to teach UML, but to show how to use it in documenting architectures. On the other hand, we also recognize that there are situations for which UML may not be the best notational choice, and we do not hesitate to show alternatives.



Extras

Related Article

An Introduction to DITA

Items

Audience

This book was written primarily for software architects and technical writers who are charged with producing architectural documentation for software projects. However, it was also written keeping in mind those who digest and use that documentation. A software architect can provide this book as a companion to his or her documentation, pointing consumers to specific sections that explain documentation organizing principles, notations, concepts, or conventions.

We assume basic familiarity with the concepts of software architecture but also provide pointers to sources of information to fill in the background. In many cases, we will sharpen and solidify basic concepts that you already may be familiar with, such as architectural views, architectural styles, and interfaces.

Contents and Organization

The book consists of a prologue and two parts. 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 architectural viewtypes, styles, and views, three concepts that provide the foundation of the book's approach to documentation. It also contains seven basic rules for sound documentation.

Part I, Software Architecture Viewtypes and Styles, introduces the basic tools for software architecture documentation: the viewtypes. A viewtype is a specification of the kind of information to be provided in a view. The three basic viewtypes are modules, component-and-connectors, and allocation. Within each viewtype reside a number of architectural styles, or specializations of the viewtype. The introduction to Part I includes a brief catalog of the styles that are described in Chapters 1-5.

• Chapter 1, The Module Viewtype: A module is an implementation unit of software that provides a coherent unit of functionality. Modules form the basis of many standard architectural views. This chapter defines modules and outlines the information required for documenting views whose elements are modules.
• Chapter 2, Styles of the Module Viewtype: This chapter introduces the prevalent styles in the module viewtype: decomposition, uses, generalization--the style that includes object-based inheritance--and layered. Each style is presented in terms of how it specializes the overall module viewtype's elements and relations.
• Chapter 3, The Component-and-Connector Viewtype: Components and connectors, used to describe the runtime structure(s) of a software system, can exist in many forms: processes, objects, clients, servers, and data stores. Component-and-connector models include as elements the pathways of interaction, such as communication links and protocols, information flows, and access to shared storage. Often, these interactions will be carried out using complex infrastructure, such as middleware frameworks, distributed communication channels, and process schedulers. This chapter introduces components and connectors and rules for documenting them.
• Chapter 4, Styles of the Component-and-Connector Viewtype: This chapter introduces some prominent styles of the componentand-connector viewtype, including communicating-processes, pipe-and-filter, client-server, peer to peer, shared data, and publish-subscribe. The chapter describes how each style is a specialization of the generic elements and relations of the viewtype, discusses what the style is useful for, and explains how it is documented.
• Chapter 5, The Allocation Viewtype and Styles: Software architects are often obliged to document nonarchitectural structures and show how their software designs are mapped to them: 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 viewtype, which is used to express the allocation of software elements to nonsoftware structures, and the three major styles of the allocation viewtype: the deployment style, which allocates software to hardware processing and communication units; the implementation style, which allocates software units to a configuration structure; and the work assignment style, which allocates software units to development teams in an organizational structure.

Part II, Software Architecture Documentation in Practice, concentrates on the complete package of architecture documentation that is incumbent on a good architect to produce. Part II completes the picture painted by Part I.

• Chapter 6, Advanced Concepts: This chapter discusses concepts that cut across viewtypes and more advanced concepts:

-Information chunking and refinement
-Context diagrams
-Combining views
-Expressing variability of the architecture
-Expressing the architecture of dynamic systems
-Creating and documenting new styles


• Chapter 7, Documenting Software Interfaces: The interfaces of the elements are a critical part of any architecture, and documenting them is an important part of the architect's overall documentation obligation. This chapter establishes the information needed to adequately specify an interface and explores the issues associated with doing so.

• Chapter 8, Documenting Behavior: This chapter covers the techniques and notations available for expressing the behavior of elements and the emergent system as it runs.

• Chapter 9, Choosing the Views: This chapter provides guidance for selecting views, given the intended use of an architecture: analysis, reconstruction, achieving common understanding, basis for deriving code, and so on. Two case studies in view selection are presented.

• Chapter 10, Building the Documentation Package: This chapter explains how the documentation is organized to serve a stakeholder. The chapter shows how the various elements discussed in the prior chapters fit together in order to produce usable documentation. It includes templates for architecture documentation.

• Chapter 11, Other Views and Beyond: This chapter ties related work to the prescriptions given in this book. The 4+1 view model of architecture is mapped to the views and documentation conventions prescribed in this book. The chapter does the same for UML diagrams, the Siemens Four Views model, the U.S. Department of Defense's C4ISR model of architecture, the recently approved ANSI IEEE standard for architecture documentation, and RM-ODP.

• Appendix A, Excerpts from a Software Architecture Documentation Package. This appendix provides an extended example of a software architecture documentation package, which demonstrates many of the concepts discussed in this book.

Stylistic Conventions

The book's main message is contained in the main flow of the text. But we have also provide extra information in the margin, including definitions, nuggets of practical advice, pointers to sources of additional information, and illuminating quotations. Advice is sometimes also called out in the body of the text. A bold term (for example view) is sometimes defined in the margin for a quick reference. These terms are also listed in the glossary. Longer diversions occur as sidebars, which are visually distinguished passages that appear at the end of a section. "Coming to Terms" sidebars tackle issues of terminology, while "Perspectives" sidebars are observations or background information written and signed by one of the authors.

Definition: A view is a representation of a set of system elements and relationships among them.

Advice: Every graphical presentation should include a key that explains the notation used.

At the end of each chapter, you can find

• A summary checklist that highlights the main points and prescriptive guidance of the chapter
• A set of discussion questions that can serve as the basis for classroom or brown-bag-lunch-group conversation
• For Further Reading, a section that offers references for more in-depth treatment of related topics

A glossary appears at the end of the book.

For More Information: Section 6.4 discusses dynamic architectures.

How to Read and Use This Book

A good notation should embody characteristics familiar to any user of mathematical notation: Ease of expressing constructs arising in problems, suggestivity, ability to subordinate detail, economy, amenability to formal proofs. (Iverson 1987, p. 341)

We distinguish between a first-time reader of this book and someone who has already read it but now wishes to use it as a companion for documenting an architecture. We also identify a "lightweight" path for those documenting small systems.

A first-time reader should concentrate on

• The Prologue, to gain an appreciation for the necessity and uses of sound architecture documentation
• The introduction to Part I, to gain an understanding of viewtypes, styles, and views and to get a glimpse of the three viewtypes and the collection of styles discussed in this book
• Sections 6.1, 6.2, and 6.3, to become familiar with the foundational concepts of view packets, refinement, context diagrams, and combining views
• Chapter 9, to learn how to choose the important views for a particular system
• Chapter 10, to learn the organizational scheme for a documentation package

In addition, the first-time reader should

• Browse through Chapters 1-5 to gain an overview of the views that can be included in a documentation package
• Read Sections 6.4 and 6.5 to gain understanding about documenting variability and dynamism, and creating new styles
• Read Chapter 7 to learn about documenting software interfaces
• Skim Chapter 8 to learn about documenting the behavior—as opposed to the structure—of a software system and its architectural elements
• Browse through Chapter 11 to see how other people have approached the problem of architecture documentation and to compare their ideas

A reader wishing to use the book as a companion in a documentation effort should consider the following strategy.

• To refresh your memory about the organization and structure of an architecture documentation package, revisit the Prologue and Chapter 10.
• Use those two selections and Chapter 9 as the basis for planning your documentation package. Let it help you match the stakeholders you have and the uses your documentation will support with the kind of information you need to provide.
• For each view you have elected to document, use the Part I chapter in which that view is discussed.
• To make sure that your documentation complies with other prescriptive methods, such as Rational's 4+1 approach, consult Chapter 11.

A reader seeking a lightweight approach to documentation should consider the strategy of reading those chapters that contain templates for documentation and then looking up those concepts that are unfamiliar. Chapter 7, Documenting Software Interfaces, and Chapter 10: Building the Documentation Package contain templates.

Commercial Tools and Notations

Heavily marketed tool suites are available for capturing design information, especially in the realm of object-oriented systems. Some of these tools are bound up with associated design methods and notations. Some tools are aimed at points in the design space other than architecture. If you have decided to adopt one of these tools and/or notations, you may wonder how the information in this book relates to you.

The answer is that we have explicitly tried to be language and tool independent. Rather than concentrate on the constraints imposed by a particular tool or notation, we have concentrated on the information you should capture about an architecture. We believe that is the approach you should take, too: Concentrate on the information you need to capture, and then figure out how to capture it using the tool you've chosen. Almost all tools provide ways to add free-form annotations to the building blocks they provide; these annotations will let you capture and record information in ways you see fit. Remember that not all the people for whom architecture documentation is prepared will be able to use the tool environment you've chosen or understand the commercial notation you've adopted.

Having said that, however, we note that the Unified Modeling Language (UML) is a fact of life and in many cases is the right choice for conveying architectural information. And so this book uses UML 1.4 in many, but not all, its examples. We also show how to use UML to represent each concept we discuss. We assume that you are familiar with the basic UML diagrams and symbology; our purpose is not to teach UML but to show how to use it in documenting architectures. On the other hand, we also recognize that in some situations, UML may not be the best notational choice, and we do not hesitate to show alternatives.



Sample Content

Online Sample Chapter

Architecture Documentation  Choosing the Views

Downloadable Sample Chapter

Click below for Sample Chapter(s) related to this title:
Sample Chapter 9

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

Preface

For all but the most trivial software systems, you cannot hope to succeed without paying careful attention to its architecture: the way the system is decomposed into constituent parts and the ways those parts interact with each other. Without an architecture that is appropriate for the problem being solved the project will fail. Even with a superb architecture, if it is not well understood and well communicated—in other words, well documented—the project will fail. Not may fail. Will fail.

Accordingly, software architecture is at the center of a frenzy of attention these days. A new book about it seems to pop out monthly. In response to industrial need, universities are adding software architecture to their software engineering curricula. It's now common for "software architect" to be a defined position in organizations, and professional practice groups for software architects are emerging. It has been the subject of major international conferences and workshops. The purveyors of the Unified Modeling Language promote their product by calling it "the standard notation for software architecture" (a claim that may say at least as much about the pervasiveness of architecture as about UML). The Software Engineering Institute maintains a bibliography of journal and conference papers about software architecture and its population is approaching 1000.

Rather surprisingly, there is a dearth of practical guidance available that is independent of language or notation for how to capture an architecture. To be sure, piles of books exist about how to use a particular language—again, UML comes to mind—but what an architect really needs is guidance in which architecture is a first-class citizen and language is relegated more appropriately to a supporting role.

First, let's agree on some basic context. The field has not anointed a single definition of software architecture, and so there are many, but we'll use this one:

A software architecture for a system is the structure or structures of the system, which comprise elements, their externally-visible behavior, and the relationships among them. (Adapted from Bass 98.)

Much of this book is about the meaning of elements and relationships, but for now we use this definition to emphasize the plurality of structures that exist in architectures. Each structure is characterized by different kinds of elements and relationships, and each structure provides a view of the architecture that imparts a particular kind of understanding.

The architecture serves as the blueprint for both the system and the project developing it. It defines the work assignments that must be carried out by design and implementation teams. The architecture is the primary carrier of system qualities such as performance, modifiability, and security, none of which can be achieved without a unifying architectural vision. Architecture is an artifact for early analysis to make sure that the design approach will yield an acceptable system. And architecture holds the key to post-deployment system understand-ing, maintenance, and mining efforts. In short, architecture is the conceptual glue that holds every phase of the project together for all of its many stakeholders.

And documenting the architecture is the crowning step to crafting it. The perfect architecture is useless if it has not been expressed understandably. If you go to the trouble of creating a strong architecture, you must go to the trouble of describing it in enough detail, without ambiguity, and organized so that others can quickly find needed information. Otherwise your effort will have been wasted, because the architecture will be unusable.

The goal of this book is to help you decide what information about an architecture is important to capture and to provide guidelines and notations (and examples) for capturing it. We intend this book to be a practitioner- oriented guide to the different kinds of information that constitute an architecture. We wanted to give practical guidance for choosing what information should be documented, and show (with examples in various notations, including but not limited to UML) how to describe that information in writing so that others can use it to carry out their architecture-based work: implementation, analysis, recovery, etc. Therefore, we cover:

• Uses of software architecture documentation. How one documents depends on how one wishes to use the documentation. We lay out possible end goals for architecture documentation, and provide documentation strategies for each.
• Architectural views. We hold that documenting software architecture is primarily about documenting the relevant views, and then augmenting this information with relevant information that applies across views. The heart of the book is an introduction to the most relevant architectural views, grouped into three major families (which we call viewtypes) along with practical guidance about how to write them down. Examples are included for each.
• Packaging the information. Once the views have been understood, there is still the problem of choosing the relevant views, including information not contained in a view, and packaging all of the information as a coherent whole. has been created, We give practical advice for all of these facets.

The audience for this book includes the people involved in the production and consumption of architectural documentation, which is to say the community of software developers.

We believe strongly in the importance of architecture in building successful systems. But no architecture can achieve this if it is not effectively communicated, and documentation is the key to successful communication. We hope we have provided a useful handbook for practitioners in the field.

PC—Austin, Texas

FB, LB, DG, JI, RL, RN, JS—Pittsburgh, Pennsylvania

0201703726P03062002

Index

Click below to download the Index file related to this title:
Index



Updates

Submit Errata

