Foreword to the First Edition

Ten years ago, I was brought in to lead the architecture team of a new and rather ambitious command-and-control system. After some rocky beginnings, the architectural design work started to proceed full speed, and the architects were finally forging ahead, inventing and resolving and designing and trying, almost in a euphoric state. We had many brainstorming sessions, filling whiteboards with design fragments and notebooks with scribblings; various prototypes validated or invalidated our reasoning. As the development team grew in size, the architects had to explain the principles of the nascent architecture to a wider and wider audience, consisting of not only new developers but also many parties external to the development group. Some were intrigued by this new concept of a software architecture. Some wanted to know how this architecture would impact them: for planning, for organizing the teams and the contractors, for delivery of the system, for acquisition of some of the system parts. Some parties wanted to influence the design of this architecture. Further removed from development, customers and prospects wanted a peek, too. So the architects had to spend hours and days describing the architecture in various forms and levels and tones to varied audiences, so that each party could better understand it.

Becoming this center of communication slowly stretched our capacity. On the one hand, we were busy designing the architecture and validating it; on the other hand, and at the same time, we were communicating to a large audience what it was and why it was that way and why we did not choose some other solution. A few months into the project, overwhelmed, we even began having a difficult time agreeing among ourselves about what it was we had actually decided.

This led me to the conclusion that “if it is not written down,
it does not exist.” This became sort of a leitmotiv in the architecture team for the following two years. As the ancient Chinese poet Lao-Tsu says in the Tao Te Ching:

Let your workings remain a mystery.
Just show people the results.

(Tablet #36)

The architecture could be whatever we had talked about, argued, imagined, or even drafted on a board, and so on. But the architecture of this system was only what was described in one major document: the Software Architecture Document (SAD). Architectural elements and architectural decisions not captured in this document simply did not exist. This one rule—“If it is not in the SAD, it does not exist.”—became our incentive to evolve and to keep the document up-to-date, almost to the week; there was also an incentive to not include anything and everything and untried ideas, as this was the project’s definite arbiter.

The SAD rapidly became a central element in the life of the project. It became our best display window for showing off our stuff, our comfort when we were down, and our shield when attacked.

The key problem we faced at the time was: What do we document for a software architecture? How do we document it? What outline do we use? What notation? How much or how little? There were few exemplars of architectural description for systems as ambitious as ours. Driven by necessity, we improvised. We made some mistakes and corrected some. We discovered rapidly that architecture is not flat but rather a multidimensional reality, with several intertwined facets, and some facets—or views—of interest to only a few parties. We found out that many readers would not even open a document that weighed more than a pound, and we would have a difficult time updating it anyhow. We realized that without capturing the reasons for our choices, we were doomed to reconstruct them again and again, every time a new stakeholder with a sharp mind came around. We picked a visual notation, not too vague and fuzzy but not too esoteric and convoluted, either, in order to not discourage most parties.

Today, software architects have a great starting point for deciding how to document their software architectures. You have it in your hands. The authors went through many experiences similar to mine and extracted the important lessons learned. They read many software architecture documents. They reviewed the academic literature, studied all the published books, checked the standards, and synthesized all this wisdom in this handbook: the essential things you need to know to define your own software architecture document. You will find guidance for the scope of software architecture; its organization; the techniques, tools, and notation to use or not to use; and comparisons, advice, and rules of thumb. In here, you’ll find the templates to get you started and the continuing guidance for when you get lost or despairing on the way.

This book is of immense value. The description and communication of software architecture is quite crucial to its many stakeholders, and this handbook should save you months of trials and errors, lots of undeserved hassle, and many costly mistakes that could potentially jeopardize the whole endeavor. It will become an important reference on the shelf of the software architect.

—Philippe Kruchten

Director of Process Development

Rational Software Canada, Vancouver