Requirements must be captured and documented. If you were the sole developer for a system on which you will also be the sole user and maintainer, you might consider designing and coding it immediately after identifying your needs. However, few system developments have such simplicity. More likely, developers and users are mutually exclusive, and stakeholders, users, developers, analysts, testers, architects, and other team members are involved. All parties must reach agreement about what system is being built.
Realities of budgets and schedules make it unlikely that all user needs are going to be satisfied in any particular release. Inevitable communication problems inherent in a multiple-person effort demand that a written document be produced to which all parties can agree and refer.
Documents that define the product to be built are typically called a requirements specification. The requirements specification for a system or application describes the external behavior of that system.
Note
For simplicity and to reflect historical usage, we'll use the term document generically in this section, but the requirements can be contained in a document, database, use-case model, requirements repository, or a combination of these elements. As we'll see in a later chapter, a "software requirements package" can be used to contain this information.
But requirements can rarely be defined in a single monolithic document, for a number of reasons.
The system may be very complex.
The customers' needs are being documented prior to documenting detailed requirements.
The system may be a member of a family of related products.
The system being constructed satisfies only a subset of all the requirements identified.
Marketing and business goals need to be separated from the detailed product requirements.
In any of these cases, you will need to maintain multiple documents and, of course, to consider a number of special cases.
One "parent" document defines requirements for the overall "system," including hardware, software, people, and procedures, and another defines requirements for just the software piece. Often, the former document is called a system requirements specification, whereas the latter is called a software requirements specification, or SRS for short.
One document defines the features of the system in general terms, and another defines requirements in more specific terms. Often, the former document is called the Vision document, whereas the latter is called a software requirements specification.
One document defines the full set of requirements for a family of products, and another defines requirements for just one specific application and for one specific release. The former document is often called a product family requirements document, or product family Vision document, whereas the latter is called a software requirements specification for a specific release of a specific application within the family.
One document describes the overall business requirements and business environment in which the product will reside, and another defines the external behavior of the system being built. Often, the former document is called the business requirements document, or marketing requirements document, whereas the latter is called a software requirements specification.
The following sections describe what to do in each case. Any or all of these cases can be combined; for example, one document could contain the full set of requirements from which selected subsets are used for specific releases, as well as all business requirements.
Although this book focuses primarily on software requirements, it's important to recognize that they are only one subset of the requirements management process in most system development efforts. As we described in Chapter 6, some systems are sufficiently complex that the only reasonable way to visualize and to build them is as a system of subsystems, which in turn are visualized as systems of subsystems, and so on, as shown in Figure 16-1. In an extreme case, such as an aircraft carrier, the system may be composed of hundreds of subsystems, each in turn having hardware and software components.
In these cases, a system-level requirements specification is created that describes the external behavior of the system, such as fuel capacity, rate of climb, or altitude ceiling, without knowledge of or reference to any of its subsystems. As we described in Chapter 6, once the requirements for the system are agreed on, a systems engineering activity is performed. Systems engineering refines a system into subsystems, describing the detailed interfaces among the subsystems, and allocating each of the system-level requirements to one or more subsystems. The resulting system architecture describes this partitioning and the interfaces among the systems.
Next, a requirements specification is developed for each subsystem. These specifications should describe the external behavior of the subsystem completely, without reference to any of its subsystems. This process causes a new class of requirements, derived requirements, to emerge. This type of requirement no longer describes the external behavior of the system except in the aggregate but instead describes the exterior behavior of the new subsystem. Thus, the process of system design creates new requirements for the subsystems of which the system is composed. In particular, the interfaces among these subsystems become key requirements: essentially, a contract between one subsystem and another, or a promise to perform as agreed to.
Once these requirements are agreed on, system design is performed again, if necessary, by breaking down each of the subsystems into its subsystems and developing requirements specifications for each. The result is a hierarchy of specifications, as shown in Figure 16-2.
At every level, requirements from the previous level are allocated to the appropriate lower-level specifications. For example, the fuel capacity requirement is allocated to the fuel control subsystem and to the fuel storage subsystem, and new requirements are discovered and defined as appropriate.
As seen in Figure 16-3, specifications that are themselves refined into additional subsystem specifications are termed system requirements specifications, or system-level requirements specifications. The lowest-level specifications, that is, those that are not further decomposed, usually correspond to software-only or hardware-only subsystems and are termed software requirements specifications or hardware requirements specifications, respectively. Further, any of the requirements specifications in Figure 16-3 may need to undergo an evolutionary process as details become better understood.
Many industries build sets of closely related products that have much functionality in common but with each containing some unique features. Such product families might be inventory control systems, telephone answering machines, burglar alarm systems, and so on.
For example, suppose that you are building a set of software products, each with some shared functionality, but that may need to share data or otherwise communicate with one another when in use. In such a case, you might consider the following approach:
Develop a product-family Vision document that describes the ways in which the products are intended to work together and the other features that could be shared.
To better understand the shared-usage model, you might also develop a set of use cases showing how the users will interact with various applications running together.
Develop a common software requirements specification that defines the specific requirements for shared functionality, such as menu structures and communication protocols.
For each product in the family, develop a Vision document, software requirements specification, and a use-case model that defines its specific functionality.
The resultant organization is shown in Figure 16-4.
The requirements specifications for the individual members may contain references—links or "traced from"—to the product-family documents or may reproduce all of the requirements from that document. The advantage of the former approach is that changes to requirements belonging to all family members can be made in just one place. However, you may need to use a requirements tool to manage these dependencies, or it will be necessary to manually examine each specific member requirements document each time the parent document is changed.
Few development efforts have the luxury of either a stable set of requirements or being able to build a system that satisfies all known requirements. During any process of requirements elicitation, requirements will arise that are deemed inappropriate for the next release of the product being constructed.
It may not be appropriate to include such requirements in the requirements specifications; we cannot afford to create any confusion about what requirements are and are not to be implemented. On the other hand, it's inappropriate to discard them, because they represent value-added work products, and we will want to harvest requirements from them for future releases. More important, the system designers may well have designed the system differently had they know that future requirements of a certain type might be likely. The best thing is to record both types of requirements somewhere in the document but to clearly identify those requirements that are planned for the current release.
Planning for a new product does not occur in a technical world devoid of business considerations. Trade-offs must be made among market windows, target markets, product packaging, distribution channels, functionality, marketing costs, resource availability, margins, ability to amortize over large numbers of copies sold, and so on.
These considerations should be documented, but they do not belong in the requirements specifications. Some organizations use a marketing requirements document (MRD) to facilitate communication among management, marketing, and developers and to assist in making intelligent business decisions, including the all-important "go, no-go" decision. The MRD also provides customers and developers with early verification of communication, to foster understanding of the product in its most general terms, and to establish the general scope of the product. The MRD should answer the following questions:
Who is the customer?
Who is the user?
What markets do we intend to sell to?
How are these markets segmented?
Are the requirements of the users in these segments different?
What classes of users exist?
What need does the product satisfy?
What kind of product is it?
What is the product's key benefits; why should someone buy it?
Who is the competition?
What differentiates the product from the competition?
In what environment will the system be used?
What will the development cost be?
At what price do you want to sell the product?
How will the product be installed, distributed, and maintained?
In Chapter 6, we performed some systems engineering on HOLIS, our home lighting automation system. At this point, we still don't know very much about HOLIS, but we probably know enough to establish a first cut at the organization for our requirements information. Figure 16-5 shows that the team is using the following elements to describe the requirements for HOLIS:
The Vision document will contain the short-term and longer-term visions for HOLIS, including basic system-level requirements and the features that are being proposed.
The system-level use-case model records the use cases by which the various actors in the system interact with HOLIS.
After some debate, the team decided to document the hardware requirements—size, weight, power, packaging—for HOLIS's three subsystems in a single hardware requirements specification.
As each subsystem of HOLIS is quite software intensive, the team decided to develop a software requirements specification for each of the three subsystems, as well as a use-case model for how each subsystem interacts with its various actors.
You'll have the opportunity to see these requirements artifacts develop further as we advance the case study in later chapters. A sample of each is included in Appendix A.
In this chapter, we examined a variety of requirements documents for systems of differing complexity. However, in most cases, requirements management eventually focuses on a single software subsystem, shrink-wrapped software product, or stand-alone application. This might be a software product, such as Microsoft Excel, Rational ClearCase, being developed by an independent software vendor, or the HOLIS lighting controls system.
In the next few chapters, we will "zoom in" on the process of requirements definition for a single software application so that we can demonstrate more clearly how the requirements management process works.