One of us was recently asked to compose a short overview on the topic of software architecture. "The field is becoming a subject of such intense study," he wrote with a twinkle in his eye, "that, believe it or not, there is a whole book coming out that explains how software architectures should be documented."
Indeed. Another one explains how they should be reviewed and evaluated. Another explains how an architecture-centric development project should be managed. Another explains how to train to be an architect. We can only guess at what else is in the pipeline. It is a sign of the field's maturity that none of these books has to dwell on the criticality of architecture in system building; they all can assume that it's a known quantity within the community of practitioners. As a group, these books are filling in the gaps in knowledge and practice that will allow architecture to graduate from a guild craft to a legitimate engineering discipline.
Helping practitioners do their job more effectively is the goal of those books, and this one is no exception. We wanted to help an architect answer the question, What do I do now? Communicating the architecture is as important a task as creating it, for without effective communication, the architecture is nothing.
Architectures are too complex to be communicated all at once, just as a high-dimension object cannot be seen or grasped in its entirety in our 3-D world. As a way to divide and conquer complexity, views are by far the most effective means of architectural communication that we know. Views, like styles and patterns, establish a specialized and shared vocabulary, allow reuse of technical knowledge and practice from one system to the next, and facilitate analysis and prediction. Relating the views to one another and making the documentation accessible to its stakeholders completes the communication obligation to the present stakeholders. Capturing the rationale and why things are the way they are completes the communication obligation to the future.
That is the essence of documentation: recognizing and discharging the architect's obligations to the community of stakeholders, present and future, whose needs the architecture is intended to serve. We hope that we have provided guidance that will lead to high-quality products and that is also practical and flexible enough to be useful in the resource-constrained, never-enough-time environments in which all architects labor.
And we look forward to discovering what's on the horizon.
Software Architectures and Documentation
Part I. Software Architecture Viewtypes and Styles
The Module Viewtype
Styles of the Module Viewtype
The Component-and-Connector Viewtype
Styles of the Component-and-Connector Viewtype
The Allocation Viewtype and Styles
Part II. Software Architecture Documentation in Practice
Documenting Software Interfaces
Choosing the Views
Building the Documentation Package
Other Views and Beyond
Rationale, Background, and Design Constraints