Modern software development requires the use of a well-structured approach to handle the development process, as well as the use of practical methodologies to document this development and manage the artifacts produced.
An essential part of this activity is documentation of the architecture of the system, which must be captured in a practical and easy-to-understand way. This book seeks to provide a methodology for just this part of the development process, and is based on work done by the authors at the Carnegie Mellon Software Engineering Institute. The target readers of the book are, mainly, software architects and technical writers, and, to some extent, software developers and project managers. The book should help them, first, to decide which architecture information needs to be documented, and, second, to write this documentation in a way that enables other stakeholders to understand, extend, and maintain the architecture (in the process of analysis, design, implementation, and deployment).
The book is divided into two main parts. The first part describes the basic approach adopted by the authors for how to document software architectures. The second part moves from the theoretical knowledge of Part 1 into practice, explaining how to apply the methodology to real projects. An appendix presents an example of architecture documentation in detail.
The book starts with a prologue, describing the role of software architecture, its relation to design, stakeholders in the software architecture, and the basic approach used in the book. One of the best features of this prologue is a quick guide to producing understandable documentation, which contains “seven rules of a sound document.”
The approach presented in the book is based on views, viewtypes, and styles. A view is defined as a “representation of a set of system elements and the relationships associated with them.” Basically, the authors use three types of views: the module viewtype, the component-and-connector viewtype, and the allocation viewtype. Styles represent a specialization of elements and relation types, or patterns that are applied to different situations (for example, the client server viewtype).
All of the chapters in Part 1 (“Foundations”) have nearly the same structure. They start with an overview, which is followed by a definition of the concepts used in the chapter that explains them in more detail, including where to use them and where not to use them, and including hints about which notations to use for them. This is followed by an explanation of how this concept relates to unified modeling language (UML). This style of presentation makes it quite easy to jump around between different chapters, if one does not really want to read them in sequential order.
Chapter 1 introduces the module viewtype, which is basically how to describe the module structure of the system. Chapter 2 introduces various styles for the module viewtype. This includes the decomposition, uses, generalization, and layered style. Chapter 3 explains the component and connector viewtype, the styles for which are presented in chapter 4. Examples of this are the pipe-and-filter, shared-date, and client server styles. Chapter 5 explains the allocation viewtypes and style. Examples of this are the deployment, implementation, and work assignment styles.
Chapters 6 through 11 explain how to use the approach in practice. This part explains advanced concepts like the use of context diagrams and documenting combined views, and also describes how to document software interfaces, including guidelines for writing interface specifications, proposals for standards for documenting interfaces, and an example of a prototypical interface document. Especially interesting is the final chapter, chapter 11, which compares the authors’ approach with other approaches, for example, the rational unified process and UML. This is quite useful, in particular for its comparison to UML, which will probably be the approach many readers will know best.
I like the sidebar approach used in the book, which includes short explanations, but it adds many pages to the text. Perhaps the publishers can try a new strategy in the next edition. I also liked the way the authors introduced architectural elements in nearly every chapter. Including a summary chapter at the end, with the subchapter “Elements, Relations, Properties,” together with the related UML descriptions, would make the text more perfect.
This book is well suited for practitioners in the area of architecture development and documentation. The approach described can be used at any stage of the software development cycle. Readers with some basic knowledge of UML, or similar methodologies, will benefit most from the book, since they will have an easier time categorizing the information supplied. Basic software engineering knowledge is also required to understand the book. The book can be used as a textbook for training readers in how to document software architectures.
