Book Review
By Mike
Tarrani
Documenting Software Architectures:
Views and Beyond
by Paul Clements (Editor), Felix Bachmann, Len
Bass, David Garlan, James Ivers, Reed Little, Robert Nord, Judith Stafford
Addison Wesley Professional; 1st edition (September 26, 2002), Hardcover:
560 pages, ISBN 0201703726, $54.99
Since reading a fascinating document titled CMU/SEI-2001-TN-010 - Documenting Software Architectures: Organization of Documentation Package a year ago and discovering that the approximately 20-page document was the basis for a book I have patiently waited, and am delighted with how the book turned out.
First, this book stands out as one of the clearest descriptions of how to not only document architectures, but how to manage the documentation project. Second, this is not a dogmatic prescription for how to document, but instead gives a set of techniques and views that can be used singularly or in combination to produce documentation that meets the needs of all technical and business stakeholders.
When I read the brief predecessor to this book I liked the way different view types and styles were introduced, but was left to my own imagination and creativity to employ them based on scant descriptions. This book rectifies those gaps by providing comprehensive guidance on how to create each view type and when it's most appropriate for inclusion into the documentation project. I was also intrigued by the earlier document because it discussed 'information chunking', which is the basis for a technique in which I'm trained and certified called Information Mapping©. The book expands on the earlier work, and it turns out that the material is not only consistent with Information Mapping© at a high level, but also shares many core principles. To me this is another plus because it will introduce readers who have not benefited from formal Information Mapping© training to powerful and effective document design and development techniques.
Another strong point about this book is the attention paid to managing the documentation process—it's one thing to write clear documentation and quite another to manage a process where many writers contribute to the documentation. I also liked the illustration examples, which epitomize how to effectively portray technical detail, and the discussion of other methods of documenting architecture.
In my opinion this book should become the standard for developing and managing documentation. It belongs on the desk of every technical writer and on the bookshelf of every architect and designer. I waited a year for this book and it was well worth the wait.
Used with the permission of Mike Tarrani, a technical consultant who can be reached via his website.
