The first thing that I liked about this book on documenting software architectures is that the authors know how to write. It is both easy to read and well-structured. The book provides a reading guide for the different categories of readers (architect, novice and stakeholders). There are also many pointers and quotes in the margins that allow you or your brain to navigate further from the current content.
“Documenting Software Architectures” starts by explaining the concepts of architecture views and styles. A second part discusses in a more detailed fashion the process of documenting architecture. My favorite content is a section that deals with the ontology of architecture decisions. Three appendixes present some techniques that can be used to describe the architecture (UML, SysML and AADL)
This book states that its goal is to answer the following question: “How do you document an architecture so that others can successfully use it, maintain it, and build a system from it?”. I think that this objective is broadly achieved. In addition, the book provides very interesting content of how to consider a software architecture. I will recommend this book to every software developers. Software architects could be the main category targeted by the book, but both software developers and software development project managers could get their share of knowledge that applies to their daily work.
Reference: “Documenting Software Architectures”, by Felix Bachmann, Len Bass & Paul Clements, Addison-Wesley
Quotes
“There are some things that we can say with confidence. Every system has an architecture. All complex systems are hierarchical in nature, but also exhibit other patterns of regularity. There’s an intimate dance that occurs between the processes of architecture and the implementation. And, to understand and reason about the architecture of a software-intensive system, one has to consider multiple views from the perspectives of specific concerns from multiple classes of stakeholders.” (Grady Booch in the foreword)
“Even the best architecture, most perfectly suited for the job, will be essentially useless if the people who need to use it do not know what it is, cannot understand it well enough to apply it, or (worst at all) misunderstand it an apply it incorrectly. All of the effort, analysis, hard work, and insightful design on the part of the architecture team will have been wasted. They might as well have gone on vacation for all the good their architecture will do. Creating an architecture isn’t enough. It has to be communicated in a way to let its stakeholders use it properly to do their jobs.”
“Architects need a way to explain their design – what drove them to make the design decisions they did. Documenting rationale is a critical but often underpracticed part of an architect’s duties.”