Documenting Software Architectures: Views and Beyond [Hardcover]

Paul Clements (Author), Felix Bachmann (Author), Len Bass (Author), David Garlan (Author), James Ivers (Author), Reed Little (Author), Robert Nord (Author), Judith Stafford (Author)

Book Description

ISBN-10: 0201703726 | ISBN-13: 978-0201703726 | Publication Date: October 6, 2002 | Edition: 1

Architecture is crucial to the success of any large software system -- but even a superb architecture will fail if it isn't communicated well. Now, there's a language- and notation-independent guide to capturing architecture so it can be used successfully by every analyst, software designer, and developer. The authors review the diverse goals and uses of software architecture documentation, providing documentation strategies for several common scenarios. They identify the basic unit of software architecture documentation: the viewtype, which specifies the type of information to be provided in an architectural view. For each viewtype -- Modules, Component-and-Connectors, and Allocation -- they offer detailed guidance on documenting what really matters. Next, they demonstrate how to package architecture documentation in coherent, usable form: augmenting architectural views with documentation of interfaces and behavior; accounting for architectural variability and dynamic systems; and more.

Editorial Reviews

From the Back Cover

"This book is of immense value. It should save you months of trials and errors, lots of undeserved hassle, and many costly mistakes that could potentially jeopardize the whole endeavor. It will become an important reference on the shelf of the software architect."
—From the Foreword by Philippe Kruchten, Rational Software Canada

"There is probably no better set of authors to write this book. The material is readable. It uses humor effectively. It is nicely introspective when appropriate, and yet in the end it is forthright and decisive....This is a tour de force on the subject of architectural documentation."
—Robert Glass, Editor-in-Chief, Journal of Systems and Software and Editor/Publisher, The Software Practitioner

For all but the most trivial software systems, you must pay close attention to the architecture—the conceptual glue that holds every phase of a project together for its many stakeholders. Without an architecture that is appropriate for the problem being solved, the project will stumble along or, most likely, fail. Even with a superb architecture, if that architecture is not well understood or well communicated—in other words, well documented—the project cannot be considered a complete success.

Although architecture is now widely recognized as a critical element in software development, there has been little guidance independent of language or notation on how to capture it. Based on the authors' extensive experience, Documenting Software Architectures helps you decide what information to document, and then, with guidelines and examples (in various notations, including UML), shows you how to express an architecture in a form that everyone can understand. If you go to the trouble of creating a strong architecture, you must also be prepared to describe it thoroughly and clearly, and to organize it so that others can quickly find the information they need.

Essential topics for practitioners include:

• Seven rules for sound documentation
• The uses of software architecture documentation, including goals and strategies
• Architectural views and styles, with general introductions and specific examples
• Documenting software interfaces and software behavior
• Templates for capturing and organizing information to generate a coherent package

0201703726B08222002

About the Author

Paul Clements is a senior member of the technical staff at the SEI, where he works on software architecture and product line engineering. He is the author of five books and more than three dozen papers on these and other topics.

Len Bass is a senior member of the technical staff at the Software Engineering Institute (SEI). He has written or edited five books and numerous papers on software engineering and other topics. He has extensive experience in architecting real-world development projects.

Robert L. Nord, a member of the software architecture program at SCR, designs and evaluates software architectures for large-scale industrial systems. Dr. Nord, currently the Siemens industrial resident affiliate at the Software Engineering Institute (SEI) in Pittsburgh, is working on methods for architecture trade-off analysis and product-line practices. His other interests include transitioning software design practices, improving architecture practices using software architecture improvement groups, and architecture-based development.

0201703726AB01162003

See all Editorial Reviews

Product Details

• Hardcover: 560 pages
• Publisher: Addison-Wesley Professional; 1 edition (October 6, 2002)
• Language: English
• ISBN-10: 0201703726
• ISBN-13: 978-0201703726
• Product Dimensions: 9.2 x 6.2 x 1.3 inches
• Shipping Weight: 1.8 pounds (View shipping rates and policies)
• Average Customer Review: 4.6 out of 5 stars  See all reviews (16 customer reviews)
• Amazon Best Sellers Rank: #952,461 in Books (See Top 100 in Books)

Customer Reviews

Most Helpful Customer Reviews

37 of 39 people found the following review helpful:

5.0 out of 5 stars The best to date, June 22, 2004

By 

wiredweird "wiredweird" (Earth, or somewhere nearby) - See all my reviews
(HALL OF FAME REVIEWER)    (TOP 500 REVIEWER)   

This review is from: Documenting Software Architectures: Views and Beyond (Hardcover)

Software architecture really is unlike any other aspect of its design. The architecture has deeper meaning and larger scale than any other aspect, and can't be discussed in the same ways.

This book opens that discussion. Among the "architecture" books I've read lately, this is the only one to offer concrete advice on describing, presenting, and analyzing archtiectural features of a system. It identifies a number of documentation types and variations. It also identifies a number of different readers - developers, future architects, users, etc. - and addresses their different documentation needs.

The authors use a little UML, but not a lot. For one thing, standard UML works at too low a level for architectural discussion. Classes, and even hierarchies of class inheritance are such fine-grained entities that architecture gernerally won't address them. Instead, the authors offer a number of diagramming styles of their own. For once, I agree with the need for non-standard notation.

Even so, I think they under-utilize the existing standards in favor of their own terminology and notation. They could have used a UML profile for lots of the discussion. It would have had to be a new profile, however, not just a force-fit of the real-time profile. They also under-used the existing architecture standards (IEEE/ANSI, DoD, NASA, and more) in favor of their own discussion. Maybe their approach can be used in any of those frameworks, but that should have been more explicit.

I see only one major flaw in this book, the assumption that a software system's architecture describes the program delivered to a customer. That's way too narrow. A large system includes things like test harnesses, debug instrumentation, application-specific QA tools, and user documentation of many kinds. Those can be major undertakings of their own. They are intimately tied to the delivered software, and may constrain the actual product.

On the postivie side, this book offer an extensive real-world case study. That probably doubles the book's value, by putting a concrete face on the otherwise abstract discussion.

There are two ways to use this book: you can agree with it, or think about it and disagree with it. If you really think about it, though, you get it's full value whether you agree or not.

In other words, you can't lose by reading this book.

39 of 42 people found the following review helpful:

5.0 out of 5 stars Should be an establish standard for documenting, October 6, 2002

By 

Mike Tarrani "www.tarrani.com" (Deltona, FL USA) - See all my reviews
(COMMUNITY FORUM 04)    (REAL NAME)   

Amazon Verified Purchase

This review is from: Documenting Software Architectures: Views and Beyond (Hardcover)

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.

8 of 8 people found the following review helpful:

5.0 out of 5 stars The Best Just got Better...., October 25, 2010

By 

T. Anderson (PA USA) - See all my reviews
(VINE VOICE)    (TOP 1000 REVIEWER)    (REAL NAME)   

Amazon Verified Purchase

This review is from: Documenting Software Architectures: Views and Beyond (2nd Edition) (Hardcover)

This book is the bible of documenting software architectures. It is a mandatory read for all software architects. It should also be read by the various stakeholders who have invested in a software architect so they have some idea about what their investment should be accomplishing.

This version includes a lot of new content. It includes new architectural styles for SOA, database models, and multi-tier architectures.

The authors have expanded the epilogue which is the comparison of Views and Beyond to other documenting approaches. It now includes comparisons to ISO/IEC 42010 - ANSI/IEEE Std 1471-2000, the RUPs 4+1, Rozanski and Woods Viewpoint Set, agile projects, and DoDAF.

The book now includes 3 appendixes. One on UML, SysML, and AADL. Each is an overview of the language.

They have improved templates based on experience gained since the first version of the book.

The book's example is now on line. It documents a Web-based service-oriented system.

This book shows you how to communicate with your stakeholders and how to address quality attribute requirements like no other book out there. I am not saying it is the best book out there, I am saying it accomplishes what it tries to teach. It creates a view of a great method of documenting architecture. It then provides a cross reference with some other great methods of documenting software architecture in the epilogue I mentioned above.

It is a must read for any architect that takes there job serious. It will add a wealth of knowledge to your arsenal of tools.