Architecture Documentation
In general I think the work done by the SEI is valuable and an asset to our field. My main concern is that the nature of projects they tend to be involved with is different than the ones I see. My guess is that they help out on the development of more tanks, electrical grids, and avionics systems than I do. I tend to see business systems (IT, banking) and web applications. The good news is that despite these differences I think we are describing different parts of the elephant rather than describing different animals.
When I started my book I had a boogeyman in mind: the chief architect.
My concern originates in the conflation of the activity of software architecture with the organizational role of an architect. It is easy to overlap these ideas when you are working on the largest scale projects because there will almost always be a chief architect and probably several other sub-system architects. On smaller projects, however, it is my belief that having a designated architect may be the wrong choice, and instead the entire team of developers should be skilled in the activity of architecting. Conflating the role with the activity has another negative side effect: developers who disdain architects, perhaps because of a bad experience from a former job, may reject the activity of architecting due to their dislike for architects.
But now on to the new boogeyman: the documentation package. This too is a good idea from the SEI that has taken an unfortunate turn. A documentation package is a relatively complete description of an architecture from many standpoints (views). It is described in the book Documenting Software Architectures (disclaimer: I helped out the many authors a bit on one of the chapters for the upcoming 2nd edition, and my advisor is one of the authors). A documentation package is also a very expensive artifact to build. My belief is that a documentation package is something you may choose to build rather than a normal step in building a system, which is a conclusion you might draw from the book. Again the SEI experience with very large systems may be causing the conflation, since if I were building a $1B system then I’d be building a documentation package for its architecture. However, most systems do not (yet) cost $1B, and most teams should not be building a documentation package.
A team may choose to build a documentation package if its quality attributes are particularly tricky to achieve, or if there are many subteams that must interact via the mechanisms and constraints laid out in the architecture. But if these conditions, or similar, are not present then a team is probably better off sketching out some of the trickiest designs and views on a whiteboard and communicating the architecture verbally, or perhaps with a minimal documentation package.
Let’s return to the idea that the SEI authors are describing the same elephant, namely the same essential principles of software architecture and engineering. The elements of a documentation package, such as modules, invariants, patterns/styles, components, and connectors, are an excellent set of elements for describing a large or small system. It is not the case that we need a different vocabulary for large, medium, and small systems. Instead, our documentation choices are different. Larger projects are going to be higher ceremony, larger bureaucracy affairs because of the need to coordinate engineering teams. Smaller projects should strive to keep bureaucracy low, which means documenting “just enough” architecture, or perhaps documenting none of it. (Note: our set of architecture abstractions is not yet perfect, as noted in the posting on What is still hard about software architecture).
I have a feeling that if my friends at the SEI were to read this that they’d be in general agreement and would go back and look for places in their writing that could have caused me to believe that these ideas were not distinct.
So if a team does not document anything, can it be architecting? Absolutely. Two developers discussing the pros and cons of using a 3-tier design vs. a 2-tier design are architecting. Choosing a language with garbage collection is a relatively low-level architecture decision (as is the converse, choosing to manually manage memory in order to get more control over latency). The activity of architecting is the engineering that goes into the design, not putting documents into a binder.
