Choosing the Views
Poetry is a condensation of thought. You write in a few lines a very complicated thought. And when you do this, it becomes very beautiful poetry. It becomes powerful poetry. The equations [of physics that] we seek are the poetry of nature.
Chen Ning Yang, 1957 Nobel Prize Winner for Physics, quoted in Bill Moyers: A World of Ideas, ed. Betty Sue Flowers, Doubleday, 1989, p. 313.
Before a view can be documented, it must be chosen by the architect. And that is the topic of this chapter: how an architect decides on the views to include in the documentation package.
In previous chapters, we explained how to represent all the various aspects of a software architecture. We discussed views that focus on coding aspects and on runtime aspects, and views that document the relationship of the software with its environment: module, C&C, and allocation viewtypes, respectively. Within a single development project, you will not document all the aspects of a software architecture. You will have to make decisions on what to document and to what level of detail. You also have to decide whether you want to define a new style to better support your project needs or to overlay two or more of the mentioned views.
But how many views are enough? How many are too many? And how complete does each view have to be? As a reader, you may be wondering whether we are going to impose an unrealistic documentation obligation on you, one that will produce beautiful exemplary documents that will never be used because the project will have run out of money at implementation time.
The reality is that all projects make cost/benefit trade-offs to pack all the work to be done into the time and the resources allocated for that work. Architecture documentation is no different. We have tried to explain the benefits of each kind of documentation and to make a compelling case for when you would want to produce it. If you can't afford to produce a particular part of the architecture documentation package, you need to understand what the long-term cost will be for the short-term savings.
Understanding which views to produce at what time and to what level of detail can be answered only in the concrete context of a project. You can determine which views are required, when to create them, and to what level of detail they have to be described in order to make the development project successful only if you know
- What people you will have: which skills are available
- What budget is on hand
- What the schedule is
- Who the important stakeholders are
This chapter is about helping you make those determinations. Once the entire documentation package has been assembled or at opportune milestones along the way, it should be reviewed for quality, suitability, and fitness for purpose by those who are going to use it.