Using Context Diagrams

In Section 6.1, we introduced the notion of walking through a view by visiting discrete chunks, which we document with view packets. We need a way to help the reader establish his or her bearings each time the scope of documentation changes, such as when we narrow our focus as the result of taking a refinement step or when we shift laterally to a sibling element at the same granularity. A context diagram serves this purpose, establishing the context for the information contained in the rest of the view packet. Unlike the architectural documentation whose scope is limited to an element of interest and its internal architecture, a context diagram is a view of that element and the environment in which it lives and contains information about both. The purpose of a context diagram is to depict the scope of the subsequent documentation and to bound the problem the element is responsible for solving.

6.2.1 Top-Level Context Diagrams

A distinguished context diagram is one for which the "element" being defined is the system. A top-level context diagram (TLCD) establishes the scope for the system whose architecture is being documented, defining the boundaries around the system that show what's in and what's out. A TLCD shows how the system under consideration interacts with the outside world. Entities in that outside world may be humans, other computer systems, or physical objects, such as sensors or controlled devices. A TLCD identifies sources of data to be processed by the system, destinations of data produced by the system, and other systems with which it must interact.

A TLCD is useful because it clarifies what constitutes the system of interest. Sometimes, an organization is asked to develop a system that is part of a larger system, and a TLCD depicts that. Sometimes, the supporting tools and environment, some off-line-processing software in a system, or some other tangential software is considered outside the scope of the system being developed. A TLCD clarifies what is in and what is out.

A system does not have just one TLCD but potentially one TLCD for each view, because the system's context can be described using the different vocabularies of the various views. A context diagram in one of the component-and-connector views shows interactions between the system of concern and its environment. A context diagram in a layered view shows which layers are within the project's scope and which are not. A TLCD for a view is associated with the view packet of that view that shows the entire system, if there is one. (Recall from Section 6.1 that not all views begin at a granularity showing the entire system.)

6.2.2 Content of a Context Diagram

Context diagrams show

• A depiction of the entitythe element or the systemwhose architecture is being documented, given with a clear delineation that distinguishes it from those entities external to it
• Sources and destinations of data or stimuli or commands processed and produced by the entity, shown outside the symbol for the entity being described and expressed in the vocabulary of the view of which the context diagram is a part
• A key that explains the notation and symbology used in the context diagram, as is the case for all graphical figures
• Other entities with which the entity being documented must interact

A pure context diagram does not disclose any architectural detail about an entity, although in practice, most context diagrams show some internal structure of the entity being put in context. Context diagrams do not show any temporal information, such as order of interactions or data flow. They do not show the conditions under which data is transferred, stimuli fired, messages transmitted, and so on.

6.2.3 Context Diagrams and Other Supporting Documentation

Context diagrams are part of the view packet's supporting documentation. As such, they impart some obligations on the other supporting documentation.

• The view packet's element catalog must explain the entities shown in the diagram. The catalog should include the interfaces between the entity being documented and the environmental entities with which it interacts, as well as behavioral descriptions of the entities and their properties. The context diagram must be accompanied by a data dictionary that describes the syntax and the semantics of the data and commands shown in the diagram. If all the entities are not fully explained in the catalog, it should be accompanied by a list of references where a reader can turn for further information about any of the entities shown in the diagram.
• The view packet's variability guide should account for variability depicted in the context diagram. Context diagrams can be used to identify unchanging, or core, elements of a product family and, by implication, the variable parts of the family. The meaning conveyed by accompanying documentation is that to build a system, one augments the core parts with instances of the noncore parts. Thus, a context diagram is a reasonable way to explain the concept of a framework.
• The view packet's rationale should explain the reasons for drawing the boundary where it is.

6.2.4 Notations for Context Diagrams

Informal Notations

Informally, context diagrams consist of a circle-and-line drawing, with the entity being defined depicted in the center as a circle, the entities external to it with which it interacts depicted as various shapes, and lines depicting interactions connecting the entities as appropriate. Because context diagrams are often used to explain systems to people who know more about the externals of the application than the internals, such diagrams can be quite elaborate and use all sorts of idiomatic symbols for entities in the environment.

UML

UML does not have an explicit mechanism for a context diagram. UML's means for showing system context are use case diagrams. Elements in a use case diagram are actors, use cases, and associations between them. Actors denote external systems and agents, such as the user. The use case icon denotes system functions. The basic symbology is shown in Figure 6.8.

Figure 6.8. Symbology of use case diagrams showing actors, associations, and use cases

One actor may be associated with several use cases. Figure 6.9 shows the UML use case diagram for a hypothetical patient monitoring system. The external entities are the patient, the nurse, and a patient log. Patient and nurse provide input to the system, and the system produces a patient log. Although this diagram provides a good overview of the functionality of the system and the external entities that interact with the system, the diagram can easily get out of control if all the possible functionality is put into this diagram.

Figure 6.9. A few use cases in a UML use case diagram, showing some context of a patient monitoring system

Other context diagrams use UML class diagrams. Figure 6.10 shows the patient monitoring system again, using a class diagram. This style of diagram contains less information, containing no description of the functionality of the system. But for more complex environments, this way of documenting the system context gives a better overview. If this style of context diagram is used, you still would expect more detailed specifications about the expected functionality of the system. Therefore, use case diagrams as shown in Figure 6.9 more naturally occur as part of the behavior description of the whole system.

Figure 6.10. Description of a system context, using a UML class diagram. The class stereotyped as «system» depicts the system whose context is shown; Patient, Nurse, and PatientLog are external entities. Different symbols are used here to distinguish people from technical things.

6.2.5 Example of a Context Diagram

Figure 6.11 shows a context diagram for the ECS system detailed in Appendix A.

Figure 6.11. A context diagram from the ECS Science Data Processing Segment as documented in Appendix A. The thick-lined rectangle in the middle depicts the system; the thin-lined rectangles around it show the external entities: people or other systems. In this context diagram, people and systems are differentiated only by the name of the box, not the shape. Replication is depicted by repeated boxes. The arrows show data flow between the system and the external entities. The external systems need to be explained in the element catalog in this diagram's view packet.