[ Team LiB ]
9.4 Documenting a View
There is no industry-standard template for documenting a view, but the seven-part standard organization
that we suggest in this section has worked well in practice. First of all, whatever sections you choose to
include, make sure to
a standard organization. Allocating specific information to specific sections will
help the documentation writer attack the task and recognize completion, and it will help the documentation
reader quickly find information of interest at the moment and skip everything else.
shows the elements and the relationships among them that populate the view.
The primary presentation should contain the information you wish to convey about the system (in the
vocabulary of that view) first. It should certainly include the primary elements and relations of the
view, but under some circumstances it might not include all of them. For example, you may wish to
show the elements and relations that come into play during normal operation, but relegate error
handling or exceptional processing to the supporting documentation.
The primary presentation is usually graphical. In fact, most graphical notations make their
contributions in the form of the primary presentation and little else. If the primary presentation is
graphical, it must be accompanied by a key that explains, or that points to an explanation of, the
notation or symbology used.
Sometimes the primary presentation can be tabular; tables are often a superb way to convey a large
amount of information compactly. An example of a textual primary presentation is the A-7E module
decomposition view illustrated in Chapter 3
. A textual presentation still carries the obligation to
present a terse summary of the most important information in the view. In Section 9.6
we will discuss
using UML for the primary presentation.
details at least those elements and relations depicted in the primary presentation,
and perhaps others. Producing the primary presentation is often what architects concentrate on, but
without backup information that explains the picture, it is of little value.
For instance, if a diagram
shows elements A, B, and C, there had better be documentation that explains in sufficient detail what
A, B, and C are, and their purposes or the roles they play, rendered in the vocabulary of the view.
For example, a module decomposition view has elements that are modules, relations that are a form
of "is part of," and properties that define the responsibilities of each module. A process view has
elements that are processes, relations that define synchronization or other process-related
interaction, and properties that include timing parameters.
To emphasize that it is but a sketch of the complete picture, we call a primary
presentation by itself an architectural
In addition, if there are elements or relations relevant to the view that were omitted from the primary
presentation, the catalog is where those are introduced and explained.
The behavior and interfaces of elements are two other aspects of an element catalog; these will be
shows how the system depicted in the view relates to its environment in the
vocabulary of the view. For example, in a component-and-connector view you show which
component and connectors interact with external components and connectors, via which interfaces
shows how to exercise any variation points that are a part of the architecture shown
in this view. In some architectures, decisions are left unbound until a later stage of the development
process, and yet the architecture must still be documented. An example of variability is found in
software product lines where the product line architecture is suitable for multiple particular systems
(discussed in Chapter 14
). A variability guide should include documentation about each point of
variation in the architecture, including
This PDF file was converted by Atop CHM to PDF Converter free version! http://www.chmconverter.com/chm-to-pdf/
Addison Wesley : Software Architecture in Practice, Second Edition
207 / 463