Synopsis of "The Contents of a Requirements Specification"

2.2 Context Section

The “Context” section of a specification sets the scene. It provides the first real taste of what the system is all about, and by the end of it, you should have a reasonably good overall picture of the nature of the system—the kinds of things it needs to do and what it doesn’t, including where its responsibilities end (that is, what’s inside and what’s outside its scope). The “Context” section aims to lead the reader—especially the nontechnical reader—into the intricacies of the system as gently as possible. The following are suggested subsections of the “Context” section, each of which is described in it own subsection below: scope, major assumptions, major exclusions, key business entities, and infrastructures.

Scope

The opening section of the requirements specification—“The Purpose of the «System name» System”—has already told readers what the system’s business aims are, so don’t repeat that here. The next step, and the aim of the “Scope” section, is to show how the system fits into the world around it: a local map showing where our territory ends and that of the neighbors starts, if you like. By far the best way to start is pictorially, with a context diagram. The full version of this chapter discusses what a context diagram should look like. The main kinds of information to show on a context diagram are

1. Components Show all the distinct pieces that must be in place for the system to work properly and how they logically connect to each other.

2. User roles Identify the main roles in which people interact with the system (either directly or indirectly). These are the system’s actors, though there is no need to explicitly call them “actors” here.

3. Scope boundary Clearly separate those parts the system is responsible for from those it is not responsible for, by enclosing everything that’s in scope within a closed line.

4. Intersystem interfaces Show all the interfaces via which the system interacts with other systems or logical components. Label them, so each one can be referred to unambiguously.

Secondary kinds of information you can consider showing are: communication links, major data stores, and grouping of components and people (that belong to the same organization or reside in the same location).

The context diagram should be followed by a brief description of each component, plus explanatory notes. Then describe all the interfaces our system has with other systems. Specifications often neglect interfaces, and this is dangerous because designing, implementing, and testing interfaces is hard work and time- consuming—so they need to be properly estimated and budgeted for. Formal requirements must be specified for the interfaces—but the “Context” section is not the best place for them (and they deserve their own section).

Major Assumptions

An assumption is an enduring statement that something can safely be treated as fact, as an axiom that can be depended upon (in the context of the system). Proclaim an assumption clearly and explicitly for each thing that you assume to be true (or, alternatively, false) and that would have significant impact on the system if it were not so.

Major assumptions that affect the system as a whole—and possibly the whole nature of the system—deserve prominence at the beginning of the requirements specification in their own section titled "Major Assumptions" or something similar. Local assumptions are best placed in context where they are relevant, dotted throughout the requirements specification.

Some authors and organizations advocate stating dependencies that the system has on external factors in a similar manner to stating assumptions, but doing so separately. External systems on which our system depends are already dealt with by specifying requirements for the interfaces to them. I prefer to regard all other dependencies as assumptions and to present them as such.

Major Exclusions

An exclusion is something the system does not do (“nongoals”). State an exclusion for any feature which is not planned but which a reader might conceivably expect to be present. The main benefit is in preemptively answering questions that reviewers might otherwise have; the exclusion gives you a place to explain why. It is good practice to write an exclusion for any suggestion that has not been acted upon. An exclusion is not a formal part of the requirements specification. So, more precisely, an exclusion points out something that the system has no obligation to implement—not that it must not. Anything the system categorically must not do should be written as a requirement. As a result, testers can ignore exclusions.

Major exclusions can be placed in their own "Major Exclusions" section at the beginning of the requirements specification for visibility, in a similar manner to major assumptions. Lesser exclusions are best placed wherever in the requirements specification they are relevant, again as lesser (local) assumptions are.

Key Business Entities

Use the "Key Business Entities” section to identify the “axis” business entities (typically one or two of them) around which the system revolves and to define the salient characteristics of each of these entities. Most commercial systems have only one, two, or three business entities at their core that drive the bulk of the processing: those things the system is built to create and manipulate.

For example, a system for a retail business might have customer and customer order as the only business entities that deserve the treatment described here.

Each key business concept needs its own subsection and should include the entity’s name in its title; “The Life-Cycle of a «Business Entity Name »” is a good title format. These entity subsections can either be grouped together within a "Key Business Entities” section or can reside directly within the "Context” top-level section.

The purpose of a section about a type of business entity is to identify its main characteristics, especially what can happen to one in its lifetime. This is where we begin to dig beneath the surface—to go beyond the superficial and the obvious. The best way to express what can happen to an entity is via a state transition diagram (sometimes called an entity life history diagram, or by UML, a state diagram). This shows all the possible states an entity can be in and how it can move from one state to another—the transitions, for each of which we need at least one function that can perform or cause it.

Infrastructures

The purpose of the “Infrastructures” section of a requirements specification is to point out any "life support mechanisms” that the system depends upon and that are not part of the system itself. Any commercial system exists solely to deliver the functions its owner needs to run their business. But those functions cannot exist in isolation, and we have to deliver lots of extra features simply to provide a well-rounded environment. Implementing some types of requirements relies on underlying software (and possibly hardware, too). For example, any requirement that involves storing data assumes we have a place to store it (typically a database). We call this an infrastructure:

Infrastructure: an underlying set of capabilities needed to support one or more types of requirements.

Infrastructures are used by the system when it is in production (at run time). Nothing that is used during the development or testing of the system is regarded as an infrastructure as far as the requirements are concerned. Likewise, infrastructures are not concerned with nontechnical logistic or operational things: policies, procedures, stationery, training, and such.

The specification of a system can’t be regarded as comprehensive unless proper requirements are specified for each infrastructure it uses; without them, there are big gaps. But the “Infrastructures” section is not the place for detailed requirements; either include them later in the main specification or write a separate specification for each infrastructure.