Documenting Software Architectures: Views and Beyond

Author: Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers List Price: $64.99 Our Price: Click to see the latest and low price ISBN: 0201703726 Publisher: Addison-Wesley Pub Co (26 September, 2002) Edition: Hardcover Sales Rank: 19,782 Average Customer Rating: 4.33 out of 5

Buy now directly from Amazon.com -

Customer Reviews

I also like the clearly articulated and illustrated advice about how to augment text with graphics, and how to select the views and associated graphics to document requirements, specifications and the finished architecture. An example of how this book goes beyond documenting just architectures is a project in which I was engaged two years ago. One of the major deliverables was a set of operations guides. While this is related to architecture with respect to how its used after it's in production, there were no books that fully described how to go about it in a coherent way. Using the advice and techniques in this book I could have greatly improved upon what I did produce. While I cannot change the past, you can be sure that I'll use this book to its fullest the next time I need to write ops guides, especially when it comes to showing component and connector views, and elements and relations.

If you do technical writing either professionally or as a part of your job get this book and keep it nearby. If you read and use the material you're ability to communicate will surely improve, and you'll be able to tailor your documentation to each segment of your audience (business and technical), as well as to clearly communicate information. You'll also learn much about managing the documentation process itself.

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.

Similar Products