Book Review - Documenting Software Architecture, 2nd. ED

Authors: Clements, Bachmann, Bass, Garlan, Ivers, Little, Merson, Nord, Stafford

Addison-Wesley, 537 pages

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!