Documenting Software Architectures: Views and Beyond

Product Author Bios

Paul Clements is a senior member of the technical staff at the SEI, where he works on software architecture and product line engineering. He is the author of five books and more than three dozen papers on these and other topics.

Len Bass is a senior member of the technical staff at the Software Engineering Institute (SEI). He has written or edited five books and numerous papers on software engineering and other topics. He has extensive experience in architecting real-world development projects.

Robert L. Nord, a member of the software architecture program at SCR, designs and evaluates software architectures for large-scale industrial systems. Dr. Nord, currently the Siemens industrial resident affiliate at the Software Engineering Institute (SEI) in Pittsburgh, is working on methods for architecture trade-off analysis and product-line practices. His other interests include transitioning software design practices, improving architecture practices using software architecture improvement groups, and architecture-based development.

"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

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:

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

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

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.

• 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.

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.

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.

How to Read and 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 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.

Customer Reviews

42 of 44 people found the following review helpful The best to date, June 22, 2004 By  wiredweird "wiredweird" (Earth, or somewhere nearby) - See all my reviews       This review is from: Documenting Software Architectures: Views and Beyond (Hardcover) Software architecture really is unlike any other aspect of its design. The architecture has deeper meaning and larger scale than any other aspect, and can't be discussed in the same ways. This book opens that discussion. Among the "architecture" books I've read lately, this is the only one to offer concrete advice on describing, presenting, and analyzing archtiectural features of a system. It identifies a number of documentation types and variations. It also identifies a number of different readers - developers, future architects, users, etc. - and addresses their different documentation needs. The authors use a little UML, but not a lot. For one thing, standard UML works at too low a level for architectural discussion. Classes, and even hierarchies of class inheritance are such fine-grained entities that architecture gernerally won't address them. Instead, the authors offer a number of diagramming styles of their own. For once, I agree with the need for non-standard... Read more Help other customers find the most helpful reviews  Was this review helpful to you?  Report abuse | Permalink  Comment 40 of 43 people found the following review helpful Should be an establish standard for documenting, October 6, 2002 By  Mike Tarrani "Jazz Drummer" (Deltona, FL USA) - See all my reviews             Amazon Verified Purchase(What's this?) This review is from: Documenting Software Architectures: Views and Beyond (Hardcover) Since reading a fascinating document titled "CMU/SEI-2001-TN-010 - Documenting Software Architectures: Organization of Documentation Package" a year ago and discovering that the approximately 20-page document was the basis for a book I have patiently waited, and am delighted with how the book turned out. First, this book stands out as one of the clearest descriptions of how to not only document architectures, but how to manage the documentation project. Second, this is not a dogmatic prescription for how to document, but instead gives a set of techniques and views that can be used singularly or in combination to produce documentation that meets the needs of all technical and business stakeholders. When I read the brief predecessor to this book I liked the way different view types and styles were introduced, but was left to my own imagination and creativity to employ them based on scant descriptions. This book rectifies those gaps by providing comprehensive guidance... Read more Help other customers find the most helpful reviews  Was this review helpful to you?  Report abuse | Permalink  Comment 1 of 1 people found the following review helpful A master guide on Architecture Documentation, July 26, 2010 By  Juan Gomez (Overland Park, KS USA) - See all my reviews    Amazon Verified Purchase(What's this?) This review is from: Documenting Software Architectures: Views and Beyond (Hardcover) Documentation is one of the main duties of a Software Architect. A master design, poorly documented, will most probably be poorly implemented. This book is an excellent guide to create long lasting documentation that effectively conveys your design and helps guides your project from conception all the way to maintenance. It gives great insight on how to successfully target your different audiences and explains in a clear and concise way a lot of the terminology used in the most widely adopted architectural styles.. The way the documentation packages are explained and organized creates a convenient and easy to follow catalog, allowing your stakeholders to employ your documentation as a reference that they keep visiting over and over again throughout the entire life-cycle of your project. The book is also organized in a way that it can be used as a reference book by the Architect or as a documentation companion for developers and business users; there are different... Read more Help other customers find the most helpful reviews  Was this review helpful to you?  Report abuse | Permalink  Comment

Share your thoughts with other customers:

› See all 8 customer reviews...

Praise For Documenting Software Architectures: Views and Beyond

In praise of Documenting Software Architectures

For many years, box and line diagrams have decorated the text that describes system implementations. These diagrams can be evocative, sometimes inspirational, occasionally informative, but are rarely precise and never complete. Recent years have brought appreciation for the importance of a deliberate structural design, or architecture, for a system. Now, in Documenting Software Architectures, we have guidance for capturing that knowledge, both to aid design and—perhaps more significantly—to inform subsequent maintainers, who hold over half the total cost of a system's software in their hands. Half of this cost goes into figuring out how the system is organized and where to make the change. A documented architecture is the essential roadmap for the system, leading the maintainer through the implementation jungle.
—Mary Shaw, Alan J. Perlis Professor of Computer Science, Carnegie Mellon University Coauthor of Software Architecture: Perspectives on an Emerging Discipline

Multiple software architecture views are essential because of the diverse set of stakeholders (users, acquirers, developers, testers, maintainers, inter-operators, and others) needing to understand and use the architecture from their viewpoint. Achieving consistency among such views is one of the most challenging and difficult problems in the software architecture field. This book is a tremendously valuable first step in defining analyzable software architecture views and frameworks for integrating them.
—Barry Boehm, TRW Professor of Software Engineering; Director, USC Center for Software Engineering

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. The philosophical elements of the book are fascinating. The authors consider concepts that few others even are aware of, present the issues related to those concepts, and then resolve them! This is a tour de force on the subject of architectural documentation.
—Robert Glass, Editor-in-Chief, Journal of Systems and SoftwareEditor/Publisher, The Software Practitioner

We found this book highly valuable for our work with our business units and would recommend it to anyone who wants to understand the needs for and improve their skills in describing software architectures for complex systems.
—Steffen Thiel, Robert Bosch Corporation

Since our projects involve numerous stakeholders, documenting the architecture from various views is of particular importance. For this task, this book provides pragmatic and well-structured guidance and will be an important reference for industrial practice.
—Martin Simons, Daimler Chrysler Research and Technology

Software architecture is an abstract representation of the most essential design decisions. It is expressed using concepts that are not directly visible in software implementation. How to identify these decisions? How to represent them? How to find the concepts that make complex software understandable? This excellent book is written by a group of expert architects sharing their experience and understanding of useful architectural concepts, essential design decisions, and practical ways to represent architectural views of complex software.
—Alexander Ran, Principal Scientist of Software Architecture, Nokia

I particularly appreciate the major theme of the book: that a software architecture consists of a variety of different structures, each defined by a set of elements and a relationship among those elements. I further appreciate the authors pointing out why the diagrams that seem so beloved by today's software designers are often deceptive and of little value. (I frequently say that in software engineering every diagram takes a thousand words to explain it.) It was also refreshing to see an explanation of why 'levels of abstraction,' a favorite term of many software designers, is an empty phrase. These are just a few of the elements that made me impatient to see this book published.
—David Weiss, Director of Software Technology Research, Avaya laboratories

The authors have written a solid book that discusses many of the most important issues facing software designers. They point out many decisions that can be considered, discussed, and made before coding begins to provide guidance for the programmers. These issues are far more important than most of the decisions that programmers focus on. Properly made and documented, the decisions discussed in this book will guide programmers throughout the remainder of the software development process.
—David Parnas, Director of the Software Engineering Programme, McMaster University

Online Sample Chapter

Architecture Documentation — Choosing the Views

Table of Contents

About the Cover.


Foreword.


Preface.


Acknowledgments.


Reader's Guide.


Prologue: Software Architectures and Documentation.

I. SOFTWARE ARCHITECTURE VIEWTYPES AND STYLES.

II. SOFTWARE ARCHITECTURE DOCUMENTATION IN PRACTICE.

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:

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.