Every process has a customer. The customer consumes or utilizes the outputs delivered by that process.

The voice of the customer is their expectations regarding what these outputs must look like and what they must do. The voice of the process is its output.

The goal of the process owner is to align the voice of the process with the voice of the customer. This alignment is what we mean by process management. One of its primary tools is continuous improvement.

Consequently, in order to “write better requirements”, we must first examine the process that produces these requirements, and then seek to improve that process.

Let’s start at the top. The solution delivery process delivers a business solution to its customer (the so-called end customer). We can think of this process has having two sub-processes: Requirements engineering and solution construction. (Note, that these two sub-processes can be executed once for any given solution, or if more iterative approaches are being used, they can be executed multiple times, where each cycle carves out functional subsets of the evolving total solution. In either case, the sub-processes remain the same.)

The requirements engineering sub-process generates the requirements specification, in other words, the requirements in our discussion. The solution construction sub-process, in turn, translates that requirements specification into an operational solution that delivers the intended value to the end customer. For a project to be considered successful this delivered value (the output of solution construction) must match the needs and expectations of the end customer as represented by the requirements specification (the output of requirements engineering).

Consequently, to write better requirements we must first seek to improve the requirements engineering process. This means aligning the voice of its process, the requirements specification, with the voice of its customer, in this case the needs and specifications of its downstream process, solution construction.

The needs and expectations of the solution construction process are indeed straightforward: A rigorous, unambiguous specification of the needs and expectations of the end customer suitable for design, construction, and implementation. Consequently, the voice of the requirements engineering customer, solution construction, consists of two required elements:

  • A clear specification of exactly what the end customer is expecting
  • A specification suitable for implementation

These two required elements imply that an effective requirements engineering process must not only capture what the end customer wants, but must capture it in a manner so the downstream process can implement a solution that delivers the intended value. This is why the quality of the requirements specification is so vital to project success. Since the solution (for it to be a success) must actually deliver tangible value in the real world, then to the extent that the requirements specification has gaps or inconsistencies, they will be “corrected” by downstream workers (designers, developers) in order to “complete” the solution so that it can be implemented. In other words, the choice is not whether one will add the necessary details and rigor needed for implementation (since nothing can be implemented without it), the only choice is who will do it and when.

Decades of research and analysis have demonstrated the overwhelming desirability of the sequence: First clearly and unambiguously understand the problem, and then, and only then, seek to solve it. In other words, requirements first, then solution.

Regardless of tools, formats, and practices, the objective of any requirements engineering process is to understand (as best we can) exactly what is needed and then to be able to capture that understanding in some tangible mode (write it down somehow) so that it can be shared and understood by others so that semantic integrity is preserved. In other words, the voice of the end customer (their needs and expectations as they understand them) must match the voice of the process (the requirements specification).

We should hasten to add that a primary way anyone understands anything is by means of successive approximations: An initial level of understanding is achieved, which is then “tested” in some way. The results of that testing are then incorporated into a next level of enhanced understanding. The cycle continues until either we run out of time or interest (the typical case, but certainly not desirable), or until we have reached a targeted level of requirements quality that characterizes the degree of understanding that we believe is necessary for success (the more desirable alternative).

In this represent-test-refine-retest cycle there are many methods for representing and testing these successive approximations to understanding.

Representation methods include English text, use cases, entity-relationship and related diagrams, UML-style object models, rigorous specification languages, and software iterations and prototypes. Testing methods typically accompany each representation technique. But, dialogue-based review sessions are by far the most prevalent---we sit down in front of the subject matter expert or knowledge worker and ask them questions and let them elaborate and clarify our understanding. Accordingly, since natural language (English in our case) is the most prevalent form of problem representation, as well as the basis for the corresponding review (“testing”) sessions, let’s examine more carefully exactly what we mean by writing better requirements in English.

A quality requirement exhibits the following four attributes:

  • Completeness. The requirement must contain all the information necessary for full understanding by the downstream customer. All assumptions must be made explicit.
  • Relevance. The requirement must exclude any information not necessary for full understanding by the downstream customer. Impertinent or extraneous material must be removed.
  • Precision. The requirement must have only one interpretation by the downstream customer.
  • Context. The requirement must explicitly identify all intended variations in usage and meaning. All pertinent meanings must be clarified. For example, the term order may have several contexts: Customer order, supplier order, purchase order, back order, etc. To the extent that these represent legitimate contexts and have different meanings, then they must be explicitly distinguished in the requirements materials.

Note that there are two sources of information that are necessary for full and unambiguous understanding: The requirements specification itself and the memories of the downstream customer. One need not document and explain everything. One only needs to capture those terms and phrases that are not part of the collective knowledge of the downstream customer. This is especially true of the many common words that are intended to retain their common and plain definitions. This determination, namely, which terms have common meanings that are also the intended meanings, and which terms require explicit clarification and elaboration for the downstream customer is a crucial role for the requirements analyst.

It should also be pointed out that quality requirements are also testable requirements. This testability criterion is another perspective on what we mean by a quality requirement. Testability is a characteristic of a requirement in which someone other than the author (for example, a test analyst, another type of downstream customer) can engineer a set of test cases and expected results that will validate that requirement. That is, determine whether it has been successfully implemented by the target solution. Testability is an exit criterion for the entire requirements engineering process.

We would like to acknowledge our colleague David Gelperin for many insights related to this posting.