Archive for October, 2012

Documenting Software Architectures

“There is no significant meaning to the arrows between the boxes”.  Ain’t that the truth! Perhaps more readily than any other profession IT architects reach for the whiteboard marker to try and explain themselves. It’s amazing given our limited symbolic repertoire, typically  boxes, arrows, clouds and stick men that we so often fail to drive out the ambiguity. Only recently I was reminded of this  when a colleague surprised me with his interpretation of a “read” arrow! Does the component read the data or does the data flow from the source to the component?

Perhaps the emergence of Archimate  has reduced the significance of this work, which is now quite old, but it is undeniable that documentation is still a challenge in many organizations and that’s not just limited to getting the budget to do it.

The book opens with a chapter on the role of architecture before covering off the basics, viewtypes,  styles and symbols, which it supports with seven pretty useful rules of documentation. That are worth repeating here.  Write from the readers point of view, avoid repetition, avoid ambiguity, easier said than done. Use standard organization, record rationale, keep the documentation current and review for fitness of purpose.

The book then pursues a three viewtype model. Module, Component and Connector and Allocation with extensive chapters on each.  These it supports with a chapter on “Advanced Concepts” which tackles the thorny questions of  how do you know when a description is complete, what to do about variability and dynamism and creating a new style. This is followed up with chapters on  View Selection, Documentation Behavior, Building the Documentation Package, before closing with a look at artifacts from RUP, Siemens 4 Views, C4ISR, ANSI /IEEE standards and RM-ODP.

Documentation is an important, but often neglected aspect of architecture. Reading this book will certainly get you thinking about it, even if you don’t agree completely there’s some thought provoking content.

Clements, Paul, Bachmann, Felix, Bass, Len, Garlan, David, Ivers, James, Little, Reed, Nord, Robert and Stafford, Judith 2003, Documenting Software Architecture Views and Beyond, Addison-Wesley, Boston


ISBN 0-21-70372-6

No Comments