Requirements & Requirements Management

Elements of Requirements Style, Part 1

By |

Writing requirements is hard! There is no simple, formulaic approach to software specification. High-quality requirements begin with proper grammar, accurate spelling, well-constructed sentences, and a logical organization. This series of four articles, adapted from my book More about Software Requirements (Microsoft Press, 2006), presents numerous style guidelines to keep in mind when writing functional requirements.

I’m not a fan of arbitrary rules about writing requirements. Some I’ve heard are:

  • A requirement may not contain the word and. An “and” indicates the presence of two requirements, which must be separated.
  • A requirement may not contain more than one sentence.
  • A requirement may not contain more than 22 words.

These sorts of simplistic rules are intended to help analysts write good requirements, but there are too many cases in which they don’t constitute good advice. As you develop your requirements specifications, remember your key objective: clear and effective communication among the project stakeholders.

I Shall Call This a Requirement

Shall is the traditional keyword for identifying a functional requirement. Functional requirements describe behaviors the system shall exhibit under certain circumstances or actions the system shall let the user take. Some people object to the use of shall because it feels stilted. It’s not the way people normally talk, at least not outside English period-piece movies. True—but so what? In fact, this is a plus. Using a distinctive word sharply separates a requirement from other information in a specification document. Shall serves as a symbol that signals the presence of a discrete requirement.

Too many requirements specifications use a random mix of different verbs: shall, must, should, could, would, is recommended, is desirable, is requested, will, can, may, and might. Many of these words are used interchangeably in casual conversation, but this can become confusing in a written specification. The reader is left to wonder whether there’s a subtle but important distinction between these various keywords. Does must have some different connotation than can? Does might (which conveys a sense of possibility in normal dialog) mean the same thing as may (which conveys a sense of permission)? I’ve also heard of conventions in which shall identifies a requirement, but will indicates a design statement and must signifies a constraint. Oh, my.

Some organizations follow a convention I find risky. In this scheme, shall indicates a function that is required, should means that the function is desired, and may indicates that the function being described is optional. This raises two problems. First, two concepts are being combined: the statement of intended functionality and the relative priority of that functionality. The second problem is that the priority information is being communicated using words that have similar meanings in everyday conversation.

My preference is to use the keyword shall to identify functional requirements whenever possible. Avoid should, may, might, and similar words that don’t make it clear whether the statement is a requirement. My colleague Brian Lawrence suggests that you replace should with probably won’t and see if that would be all right with the customer. It probably won’t.

A requirement in the form, “The system should do X” can be restated in the form, “When Y happens, the system shall do X.” And instead of using the shall–should–may convention to communicate priority, I’d rather see requirements written as follows:

  1. “The system shall … [Priority = High].”
  2. “The system shall … [Priority = Medium].”
  3. “The system shall … [Priority = Low].”

The goal of clear and unambiguous communication is more elusive when requirements writers use a mix of nearly synonymous verbs and expect all readers to reach the same conclusions about what they’re trying to say. Frankly, I don’t understand the objection to shall. But if you don’t like it, pick an alternative word—such as must—and use it consistently.

System Perspective or User Perspective?

Various conventions for writing functional requirements exist. Some people believe that requirements should describe only the system’s behavior, because “the system” is what you create by implementing all the functional requirements. However, I think it’s appropriate to write functional requirements from either the system’s perspective or the user’s perspective. Use whichever structure offers the clearest communication in a given situation.

Requirements written from the system’s perspective conform to the following general structure:

Conditions:   “When [some conditions are true]…”

Result:          “… the system shall [do something]”

Qualifier       “…[response time goal or quality objective].”

The “conditions” part of the requirement could reflect an event that triggers the system to respond in some way. Here’s a simple example, from an information system for ordering meals on-line from a company cafeteria:

“When the patron indicates that he does not wish to order any more food items, the system shall display all food items ordered, the individual food item prices, and the total payment amount within 1 second.”

This requirement describes an event that the system can detect, followed by the action the system takes in response to that event. This requirement also includes a performance goal, the 1-second response time. This element constitutes a nonfunctional requirement associated with this specific bit of system functionality.

When stating such performance goals, it’s important to make clear whether they are critical values or merely desirable targets. Is the system acceptable if it takes 1.2 seconds to display the order details? How about 10 seconds? Precise response times are more critical for hard real-time systems than for information systems.

In some cases, it makes more sense to describe actions that the system will let the user take under particular circumstances. When writing functional requirements from the user’s perspective, keep the following general structure in mind:

User type:     “The [user class or actor name]…”

Result type:   “… shall be able to [do something]…”

Object:         “… [to something].

Qualifier:      [response time goal or quality objective]

It’s more meaningful to refer to the affected user class by name, rather just saying user. Here’s an illustration of a functional requirement written from the user’s perspective:

“The patron shall be able to reorder any meal he had ordered within the previous six months, provided that all food items in that order are available on the menu for the meal date.”

Note that these examples are written in the active voice. They explicitly identify the entity—the system or a specific user type—that takes each action. Most of the functional requirements I read are written in passive voice:

Passive: “When the output state changes, it is logged in the event log.”

Whenever you can, recast such requirements in the much clearer active voice:

Active: “When the output state changes, the system shall record the new state and the time of the state change in the event log.”

With active voice, the reader doesn’t have to deduce which entity is doing what. The more explicit and precise you can make the requirements, the easier it will be for the readers to understand them and use them to guide the project work they do.

This is the first of a four-part series. Check back soon for Elements of Requirements Style, Parts 2, 3 and 4.

 

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

Latest posts by Karl Wiegers (see all)