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.