Customer Reviews

Documenting Software Architectures: Views and Beyond

5 star:		(11)
4 star:		(3)
3 star:		(2)
2 star:		(0)
1 star:		(0)

 

 

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.

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.

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.

This is one of those books about which it is difficult to say enough good things. I found the first edition very influential on my on thinking to say nothing of enlightening. Impressively, the authors have improved this second edition, for example moving the comprehensive sample documentation online, thus making room for more of the lucid and rational explanation of documentation practices that made the first edition so useful.

I usually include a discussion of who would benefit from a reading in my reviews. Anybody who thinks they might be producers or consumers of software architecture documentation owes it to themselves to get a copy of this book now. Others might think they have no need for this book, but still should read it. This includes Business Analysts, who, this book makes clear, are stakeholders of software architectures. BAs will also their thinking sharpened on how to develop useful documentation and use graphical notation in a precise and meaningful fashion.

This book is on my short list of classics of software engineering. It is a book I return to often. Reading this second edition, even after being fully familiar with the first, was still a richly satisfying experience. I cannot recommend this book enough.

The goal of this book is to first help the reader understand what software architecture is and then how to best communicate details about specific plans or implementations. It reaches both goals admirably.

Documentation is one of the main duties of a Software Architect. A master design, poorly documented, will most probably be poorly implemented. This book is an excellent guide to create long lasting documentation that effectively conveys your design and helps guides your project from conception all the way to maintenance.

It gives great insight on how to successfully target your different audiences and explains in a clear and concise way a lot of the terminology used in the most widely adopted architectural styles.. The way the documentation packages are explained and organized creates a convenient and easy to follow catalog, allowing your stakeholders to employ your documentation as a reference that they keep visiting over and over again throughout the entire life-cycle of your project.

The book is also organized in a way that it can be used as a reference book by the Architect or as a documentation companion for developers and business users; there are different "paths" through the book, targeted to different audiences and conveniently outlined on the preface.

I can't wait for the second edition to come out! (already pre-ordered)

Simply put, I think this book represents the best thinking about documenting software architectures. You can find other books that include different aspects covered in this book (documenting views, 4+1, ANSI/IEEE-1471-2000, etc). However, you will have a hard time finding a book that pulls it all together, provides the rationale and includes the "beyond" part which discusses other approaches to documenting software architectures and how they relate to the "Views and Beyond" (V&B) approach. For instance, the book discusses how to use V&B to comply with ANSI/IEEE-1471-2000.

Clements shows how to use various notations to document your software design. Of these, perhaps UML is now the most common. The advice in the text can be used to first design your code, before programming. Certainly, you should somehow have a design laid out first. You do, don't you?

The book offers structural advice about how to do this. From the low level "mechanical" details of the UML notation, to more general conceptual issues. Various possible architectures are outlined. Client-server, n-tier and peer-to-peer. Enough to get you started in implementing these ideas.

I would highly recommend this book to experienced architects who want to consolidate their knowledge and learn a thing or two about the latest thinking on architecture documentation.

As a software tester, I rely heavily on system documentation. Unfortunately, documentation is often missing, obsolete, or never created in the first place.

Also, I have a great appreciation for software architects and the work they produce. As a former developer, I used to struggle with the best ways to express system architecture diagrams. After all, there are so many methods available to document systems - UML being a major one, but there are others.

When I started reading this book, I was struck by its practicality, beautiful simplicity, and integration between authors. Everything I read in this book is written in a clear and understandable way. The authors understand that different audiences will read this book, so they give graphical (of course) guidance in which chapters are most applicable to architects, stakeholders and novices.

This book covers the basics, such as module views and module styles, component and connector views, allocation views and styles. Part two of the book goes beyond the basics and gets into issues regarding levels of detail, deciding among alternatives, documenting interfaces and documenting behavior. Part three is devoted to building the architecture documentation.

There are appendices devoted to UML, SysML and AADL to show how architectural documentation is shown in each of these.

It would be tempting to say that this book is needed for new technologies, such as SOA and the cloud, which is true, but too narrow. Actually, this book can be applied to any technology or approach - traditional, agile, iterative, or anything. That's because the one thing people ask for and struggle with is documentation. This is especially true for architectural documentation.

Read this book and apply the things in it and you will stand out on projects - in a good way. And, of course, that's a good thing!