Documenting Software Architectures: Views and Beyond
Software architecture—the conceptual glue that holds every phase of a project together for its many stakeholders—is widely recognized as a critical element in modern software development. Practitioners have increasingly discovered that close attention to a software system’s architecture pays valuable dividends. Without an architecture that is appropriate for the problem being solved, a project will stumble along or, most likely, fail. Even with a superb architecture, if that architecture is not well understood or well communicated the project is unlikely to succeed.
Documenting Software Architectures, Second Edition, provides the most complete and current guidance, independent of language or notation, on how to capture an architecture in a commonly understandable form. Drawing on their extensive experience, the authors first help you decide what information to document, and then, with guidelines and examples (in various notations, including UML), show you how to express an architecture so that others can successfully build, use, and maintain a system from it. The book features rules for sound documentation, the goals and strategies of documentation, architectural views and styles, documentation for software interfaces and software behavior, and templates for capturing and organizing information to generate a coherent package.
Review By: J.D. Baker
04/08/2011I received the first edition of this book when I attended the SEI class on documenting software architectures. I was prepared to skim the second edition and write a quick review, but as I started to read it, I realized that this edition has a lot to offer beyond what is in the first edition. If I had to describe the book in one word, it would be “comprehensive.” The authors have included information that should be valuable to anyone who is creating software architecture descriptions, as well as anyone who needs to be able to read and understand those descriptions. The difficulty will be in determining what is useful and appropriate for a given situation. The authors have attempted to help by providing numerous sidebars of advice, perspectives, and examples. In support of the book, they have created a website (http://wiki.sei.cmu.edu/sad) with a fully populated example of a software architecture document.
Some of the notable improvements over the first edition are:
- A much more reasoned inclusion of UML as the notation for documenting architectures
- The inclusion of appendices providing an overview of UML, SysML, and AADL
- An illuminating report on a discussion of patterns and styles, how they differ, and how they are the alike
- An expanded collection of styles, including an aspects style for describing cross-cutting concerns and an SOA style
This book is about documenting software architectures, but that doesn't mean notebooks on a shelf that no one reads. I have produced architecture documentation using a wiki, and I found the authors’ advice regarding online documentation to be very sound. The one thing that I might add in this area, depending on the culture of your organization and customers, is to select a wiki or content-management solution that makes it easy to produce a printed copy of the documentation.
The most interesting notion in the book is the authors’ statement that not every view comes from a published style or pattern. This is an important concept. Of course, they offer suggestions and advice for what to do when this occurs.
My favorite chapter is “Reviewing an Architecture Document.” For some years now, I have attempted to create an architecture review guide. This has been somewhat of a struggle, because there is a shortage of published information. Because this was a book written by the SEI, I expected a rehash of their Architecture Tradeoff Analysis Method for evaluating architectures. Instead, this is a chapter rich with procedures, questions, and experience-based advice on conducting purposeful reviews.
I have looked at every page of this book, but it is so dense with information that it will take repeatedly reading applicable sections before I'll believe that I've gotten everything I can out of it.