Reader’s Guide
Audience
There are three primary audiences for this book.
1. Software architects who are charged with producing architecture documentation for software projects. For these people we tried to answer the question “What information do I need to capture about my architecture, and what notations and techniques are available for communicating it clearly and usefully in a timely fashion?”
2. Stakeholders of an architecture who must digest and use the documentation they receive from the architect or architecture team. 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.
3. People who wish to learn introductory concepts about software architecture. By establishing the purposes and uses of software architecture (and hence, its documentation), and by establishing a basic set of concepts important in the creation and communication of architecture, this book serves as an introduction to the subject.
We assume basic familiarity with the concepts of software engineering. In many cases, we will sharpen and solidify basic concepts that you already know, such as architecture views, architecture styles, and interfaces.
Stylistic Conventions
The book’s core message is contained in the main flow of the text. But we also provide extra information in the margins, including
• Definitions: Where we introduce a term such as view, we make it bold and underlined; a margin note adjacent to that line gives the definition. These terms are also listed in the glossary at the end.
A view is a representation of a set of system elements and relationships among them.
• Nuggets of practical advice.
Every graphical presentation should include a key that explains the notation used.
• Pointers to sources of additional information, either within this book or outside.
The prologue contains an introduction to the basic architecture concepts used in this book.
• Illuminating quotes that we hope will add to the fullness of the message.
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.
—Ken Iverson (1987, p. 341)
Advice that won’t fit into a margin note will be called out in the body of the text. 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 or more 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
All architects should
• Read the introduction to Part I, to gain an understanding of styles and views, and to get a glimpse of the collection of styles discussed in this book.
• Browse Chapters 1–5 to gain a deeper understanding of the views that might be used in your documentation. Later, once you’ve chosen a set of views to document, you can read about them in more depth as needed.
• Read Chapter 10, to learn the organizational scheme for a documentation package.
• Read Chapter 9, to learn how to choose the important views for a particular system. This will let you plan your documentation package, matching your stakeholders and the uses your documentation will support with the kind of information you need to provide.
• Browse the sections in Chapter 6 to learn about documenting variability, context diagrams, and other helpful concepts. Come back and concentrate on these as needed.
• Read Chapters 7 and 8 to learn about documenting software interfaces and documenting behavior of a system.
• Consult Chapter 11 to see how your architecture document should be reviewed, so that you can better position it for a successful review by giving reviewers the information they need.
• If you are interested in making your documentation compliant with other prescriptive methods, such as IBM Rational’s 4+1 approach or ISO/IEC 42010, consult the epilogue.
An architecture stakeholder using an architecture document written with the precepts of this book may wish to consult this book to gain a deeper understanding. You should
• Read Chapter 10 to gain a better understanding of the layout of the document, and how the layout achieves coverage of the architectural information being conveyed.
• Consult other chapters as necessary to provide more insight into specific parts of the architecture document. For example, you may wish to read the introduction to Part I to learn about module, component-and-connector, and allocation styles, and then consult the chapter on a specific style.
• Read Chapter 11 if your job is to conduct or participate in a review of the architecture document.
Readers who wish to learn introductory concepts about software architecture should
• Read the prologue to learn what software architecture is, why it is important, and the critical role of documentation in a development project.
• Read the introduction to Part I, to gain an understanding of styles and views, and to get a glimpse of the collection of styles discussed in this book.
• Read Chapters 1–5 to become familiar with some architecture styles that are widely used in modern software systems.
• Browse Chapters 7 and 8 to learn about the important architecture concepts of interfaces and behavior.
• Consult Chapter 10 to see a format for an architecture document.
• Browse the appendices to help you understand the examples in the book if you’re not familiar with the notations.
