Preface
The purpose of this book is to answer the following question:
How do you document an architecture so that others can successfully use it, maintain it, and build a system from it?
The audience for this book includes all the people involved in the production and consumption of architecture documentation. The goal of this book is to help you decide what information about an architecture is important to capture and to provide guidelines, notations, and examples for capturing it. We intend this book to be a practitioner-oriented guide to the various kinds of information that constitute an architecture. We give practical guidance for choosing what information should be documented and show—with examples in various notations, including but not limited to the Unified Modeling Language (UML)—how to describe that information in writing so that others can use it to carry out their architecture-based work: implementation, analysis, and recovery. We also show how to create a comprehensive software architecture document that others can use.
Although piles of books exist about how to use a particular notation (UML comes to mind), we believe what an architect really needs is guidance in which architecture and its stakeholders are the first-class citizens, and language is relegated more appropriately to a supporting role. That’s what we’ve tried to provide with this book.
Languages and Tools for Architecture
Commercial languages and 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, notations, and commercial products. 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, will this book relate to you?
Very few things become obsolete faster than references to specific tools, so we’ve avoided those. Instead, 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 an available tool. Almost all tools provide ways to add free-form annotations to the building blocks they provide; if all else fails, 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 acknowledge that a few standard languages and notations have come to dominate, chief among them UML. And so this book provides a plethora of examples showing UML 2 representing the architecture views we cover, as well as other concepts such as refinement and behavior. If you have chosen UML as your modeling language, you’ll feel at home.
Appendix A contains a summary of UML’s visual notation and its applicability to document the concepts in this book. Appendices B and C summarize the Systems Modeling Language (SysML) and the Architecture Analysis and Design Language (AADL), respectively. Our purpose is not to teach these languages, but to offer a quick refresher for those familiar with them and a flavor-providing introduction for everyone else.
What’s New in the Second Edition
• A number of new architecture styles have entered the mainstream, and this edition talks about documenting those. These include service-oriented architectures, multi-tier architectures, and architectures for aspect-oriented systems. We also treat the architecture-level documentation of a software system’s data model, as well as its installation and production environment, as first-class styles.
• This edition is much more Agile-friendly, orienting its advice to be consistent with the Agile Manifesto’s entreaty to value working software over comprehensive documentation.
• We treat the systematic documentation of rationale with much greater depth, reflecting best industrial practices. We’ve added a new chapter about reviewing an architecture document to make sure it’s serving its stakeholders as intended.
• The suggested templates for architecture documentation have several improvements, reflecting years of use and feedback. They are also more flexible, and we lay out different options for arranging your documentation.
• We have replaced the comprehensive example of a documented software architecture with a new one. The architecture is for a Web-based service-oriented system, more in today’s industrial mainstream. To make the book smaller and allow us to maintain the example over time, we put the example online. And many of our in-line examples have been replaced or updated.
• Since the first edition was published, the Unified Modeling Language has graduated to version 2.0 and beyond. That opened up new possibilities for more straightforwardly documenting various architecture constructs, especially components and connectors. Where necessary, our figures are updated to reflect the new constructs.
• This edition has concise appendices summarizing three important languages and notations useful for documenting architectures: UML, AADL, and SysML. Each appendix constitutes a mini-reference guide on the language.
• Finally, this edition reflects the experience we’ve gained with Views and Beyond in the intervening years since the first edition was published. This experience has come from creating documented architectures for very challenging systems, and helping other people do so. It also comes from using architecture documentation in practice, such as when we evaluate other organizations’ software architectures. Finally, it has come from interacting with more than a thousand participants in our two-day industrial course based on the book. These interactions with practicing software architects have let us make our advice more prescriptive and crisp and reflect the problems and situations that architects face daily.
Complete Example of a Software Architecture Document Online
You can see a fully worked-out example of a software architecture document using the approaches and templates described in this book at wiki.sei.cmu.edu/sad.
—P.C.
Austin, Texas
—F.B., L.B., D.G., J.I., R.L., R.N.
Pittsburgh, Pennsylvania
—P.M.
Brasilia, Brazil
—J.S.
Boston, Massachusetts