In an ideal world, every individual business, user, functional, and nonfunctional requirement would exhibit the qualities described in the following sections.

It’s not enough to have excellent individual requirement statements. Sets of requirements that are grouped into a baseline for a specific release or iteration should exhibit the characteristics described in the following sections, whether they are recorded in an SRS document, a requirements management tool, a set of user stories and acceptance tests, or any other form.

You can write functional requirements from the perspective of either something the system does or something the user can do. Because effective communication is the overarching goal, it’s fine to intermingle these styles, phrasing each requirement in whichever style is clearer. State requirements in a consistent fashion, such as “The system shall” or “The user shall,” followed by an action verb, followed by the observable result. Specify the trigger action or condition that causes the system to perform the specified behavior. A generic template for a requirement written from the system’s perspective is ([ref163]):

This template is from the Easy Approach to Requirements Syntax (EARS). EARS also includes additional template constructs for event-driven, unwanted behavior, state-driven, optional, and complex requirements. Following is an example of a simple functional requirement that describes a system action using this template:

This example includes a precondition, but not a trigger. Some requirement writers would omit the phrase “the system shall” from this requirement. They argue that, because the requirements are describing system behavior, there’s no need to repetitively say “the system shall” do this or that. In this example, deleting “the system shall” is not confusing. Sometimes, though, it’s more natural to phrase the requirement in terms of a user’s action, not from the system’s perspective. Including the “shall” and writing in the active voice makes it clear what entity is taking the action described.

When writing functional requirements from the user’s perspective, the following general structure works well ([ref005]):

Alternative phrasings are “The system shall let (or allow, permit, or enable) the [a particular user class name] to [do something].” Following is an example of a functional requirement written from the user’s perspective:

Notice how this requirement uses the name of the user class—Chemist—in place of the generic “user.” Making the requirement as explicit as possible reduces the possibility of misinterpretation.

Writing requirements isn’t like writing either fiction or other types of nonfiction. The writing style you might have learned in school in which you present the main idea, then supporting facts, then the conclusion, doesn’t work well. Adjust your writing style to put the punch line—the statement of need or functionality—first, followed by supporting details (rationale, origin, priority, and other requirement attributes). This structure helps readers who are just skimming through a document, while still being useful for those thorough readers who need all the details. Including tables, structured lists, diagrams, and other visual elements helps to break up a monotonous litany of functional requirements and provides richer communication to those who learn best in different ways.

Nor are requirements documents the place to practice your creative writing skills. Avoid interleaving passive and active voice in an attempt to make the material more interesting to read. Don’t use multiple terms for the same concept just to achieve variety (customer, account, patron, user, client). Being easy to read and understand is an essential element of well-written requirements; being interesting is, frankly, less important. If you are not a skilled writer, you should expect that your readers might not understand what you intend to convey. Keep the tips that follow in mind as you craft your requirements statements for maximum communication effectiveness.

Clarity and conciseness Write requirements in complete sentences using proper grammar, spelling, and punctuation. Keep sentences and paragraphs short and direct. Write requirements in simple and straightforward language appropriate to the user domain, avoiding jargon. Define specialized terms in a glossary.

Another good guideline is to write concisely. Phrases like “needs to provide the user with the capability to” can be condensed to “shall.” For each piece of information in the requirements set, ask yourself, “What would the reader do with this information?” If you aren’t certain that some stakeholder would find that information valuable, perhaps you don’t need it. Clarity is more important than conciseness, though.

Precisely stated requirements increase the chance of people receiving what they expect; less specific requirements offer the developer more latitude for interpretation. Sometimes that lack of specificity is fine, but in other cases it can lead to too much variability in the outcome. If a developer who reviews the SRS isn’t clear on the customer’s intent, consider including additional information to reduce the risk of problems later on.

The keyword “shall” A traditional convention is to use the keyword “shall” to describe some system capability. People sometimes object to the word “shall.” “That’s not how people talk,” they protest. So what? “Shall” statements clearly indicate the desired functionality, consistent with your overarching objective of clear and effective communication. You might prefer to say “must,” “needs to,” or something similar, but be consistent. I sometimes read specifications that contain a random and confusing mix of requirements verbs: shall, must, may, might, will, would, should, could, needs to, has to, should provide, and others. I never know if there are differences between the meanings of these or not. Nuances between different verbs also make the document far more difficult for cross-cultural teams to interpret consistently. You’re better off sticking with a keyword such as “shall.”

Some requirement authors deliberately use different verbs to imply subtle distinctions. They use certain keywords to connote priority: “shall” means required, “should” means desired, and “may” means optional ([ref124]). We regard such conventions as dangerous. It’s clearer to always say “shall” or “must” and explicitly assign high, medium, or low priority to each requirement. Also, priorities will change as iterations proceed, so don’t tie them to the phrasing of the requirements. Today’s “must” could become tomorrow’s “should.” Other authors use “shall” to indicate a requirement and “will” to denote a design expectation. Such conventions run the risk of some readers not understanding the distinctions between words people use interchangeably in everyday conversation; they are best avoided.

Active voice Write in the active voice to make it clear what entity is taking the action described. Much business and scientific writing is in the passive voice, but it is never as clear and direct as using the active voice. The following requirement is written in passive voice:

The phrasing “will be updated” is indicative of passive voice. It denotes the recipient of the action (serial number) but not the performer of the action. That is, this phrasing offers no clue as to who or what updates the serial number. Will the system do that automatically, or is the user expected to update the serial number? Rephrasing this requirement into active voice makes the actor explicit and also clarifies the triggering event:

Individual requirements Avoid writing long narrative paragraphs that contain multiple requirements. Readers shouldn’t have to glean the individual requirements embedded in a mass of free-flowing descriptive language. Clearly distinguish individual requirements from background or contextual information. Such information is valuable to readers, but they need to unambiguously recognize the actual requirement statements. I once reviewed a large requirements specification written in the form of long paragraphs. I could read a full page and understand it, but I had to work hard to pick out the discrete requirements. Other readers might well come to different conclusions of exactly what requirements were lurking in that mass of text.

Words such as “and,” “or,” “additionally,” or “also” in a requirement suggest that several requirements might have been combined. This doesn’t mean you can’t use “and” in a requirement; just make sure the conjunction is joining two parts of a single requirement instead of two separate requirements. If you would use different tests to verify the two parts, split the sentence into separate requirements.

Avoid using “and/or” in a requirement; it leaves the interpretation up to the reader, as in this case:

This requirement would permit the user to enter one, two, or three numbers at once when performing a single search. That might not be what’s intended.

The words “unless,” “except,” and “but” also indicate the presence of multiple requirements:

Failing to specify what happens when the “unless” clause is true is a common source of missing requirements. Split this into two requirements to address the behavior for the two conditions of the credit card being active and expired:

and

Requirements need to be specified at a level of precision that provides developers and testers with just enough information to properly implement them.

Appropriate detail An important part of requirements analysis is to decompose a high-level requirement into sufficient detail to clarify it and flesh it out. There’s no single correct answer to the commonly asked question, “How detailed should the requirements be?” Provide enough specifics to minimize the risk of misunderstanding, based on the development team’s knowledge and experience. The fewer the opportunities for ongoing discussion about requirements issues, the more specifics you need to record in the requirements set. If a developer can think of several possible ways to satisfy a requirement and all are acceptable, the specificity and detail are about right. You should include more detail when ([ref247]):

It’s safe to include less detail when:

Consistent granularity Requirement authors often struggle to find the right level of granularity for writing functional requirements. It’s not necessary to specify all of your requirements to the same level of detail. For example, you might go into more depth in an area that presents higher risk than others. Within a set of related requirements, though, it’s a good idea to try to write functional requirements at a consistent level of granularity.

A helpful guideline is to write individually testable requirements. The count of testable requirements has even been proposed as a metric for software product size ([ref252]). If you can think of a small number of related test cases to verify that a requirement was correctly implemented, it’s probably at an appropriate granularity. If you envision numerous and diverse tests, perhaps several requirements are combined and ought to be separated.

I’ve seen requirement statements in the same SRS that varied widely in their scope. For instance, the following two functions were split out as separate requirements:

These requirements are very fine-grained. They will need few tests for verification of correct behavior. You can imagine a tediously long list of similar requirements, which would better be expressed in the form of a table that lists all the keystroke shortcuts and how the system interprets them.

However, that same SRS also contained a functional requirement that seemed rather large in scope:

This single requirement—seemingly no larger or smaller than all the others in the SRS—stipulated the inclusion of a complex speech-recognition subsystem—virtually an entire product in its own right! Verifying this one requirement in the working system could require hundreds of tests. The requirement as stated here could be appropriate at the high level of abstraction found in a vision statement or a market requirements document, but the speech-recognition requirement clearly demands much more functionality detail.

Readers’ eyes glaze over when confronting a dense mass of turgid text or a long list of similar-looking requirements. Consider the most effective way to communicate each requirement to the intended audience. Some alternatives to the natural language requirements that we’re used to are lists, tables, visual analysis models, charts, mathematical formulas, photographs, sound clips, and video clips. These won’t suffice as substitutes for written requirements in many cases, but they serve as excellent supplemental information to enhance the reader’s understanding.

I once saw a set of requirements that fit the following pattern:

There were 3 possible values for <format> and 4 possible values for <jurisdiction>, for a total of 12 similar requirements. The SRS did indeed contain 12 such requirements, but one of the combinations was missing and another was duplicated. You can prevent such errors by representing these types of requirements in a table, which is more compact and less boring than a requirements list. The generic requirement could be stated as:

The cells in the table contain only the suffix to append to the master requirement’s identifier. For example, the third requirement in the top row expands to:

If any of the combinations don’t have a corresponding functional requirement for some logical reason, put N/A (not applicable) in that table cell. This is much clearer than omitting the irrelevant combination from the long list and then having a reader wonder why there is no requirement for parsing documents containing territorial laws in the untagged format. This technique also ensures completeness in the requirements set—if there’s something in every cell, you know you haven’t missed any.

Requirements quality is in the eye of the reader, not the author. The analyst might believe that a requirement he has written is crystal clear, free from ambiguities and other problems. However, if a reader has questions, the requirement needs additional work. Peer reviews are the best way to find places where the requirements aren’t clearly understood by all the intended audiences. This section describes several common sources of requirements ambiguity.

Fuzzy words Use terms consistently and as defined in the glossary. Watch out for synonyms and near-synonyms. I know of one project where four different terms were used to refer to the same item in a single requirements document. Pick a single term and use it consistently, placing synonyms in the glossary so people who are accustomed to calling the item by a different name see the connection.

If you use a pronoun to refer to something mentioned earlier, make sure the antecedent is crystal clear. Adverbs introduce subjectivity and hence ambiguity. Avoid words like reasonably, appropriately, generally, approximately, usually, systematically, and quickly because the reader won’t be sure how to interpret them.

Ambiguous language leads to unverifiable requirements, so avoid using vague and subjective terms. Table 11-2 lists many such terms, along with suggestions for how to remove the ambiguity. Some of these words might be acceptable in business requirements, but not in user requirements or specific functional requirements that are attempting to describe the solution to be built.

The A/B construct Many requirements specifications include expressions in the form “A/B,” in which two related (or synonymous, or opposite) terms are combined with a slash. Such expressions frequently are ambiguous. Here’s an example:

This sentence could be interpreted in several ways:

Sometimes authors use the A/B construct because they aren’t sure exactly what they have in mind. Unfortunately, this means that each reader gets to interpret the requirement to mean whatever he thinks it ought to mean. It’s better to decide exactly what you intend to say and choose the right words.

Boundary values Many ambiguities occur at the boundaries of numerical ranges in both requirements and business rules. Consider the following:

This phrasing makes it unclear as to which category vacation requests of exactly 5 days and exactly 10 days belong. It gets even more confusing if fractions are involved, like 5.5 days of vacation. The words “through,” “inclusive,” and “exclusive” make it totally clear whether the endpoints of the numerical range lie inside or outside the range:

Negative requirements People sometimes write requirements that say what the system will not do rather than what it will do. How do you implement a don’t-do-this requirement? Double and triple negatives are particularly tricky to decipher. Try to rephrase negative requirements into a positive sense that clearly describes the restricting behavior. Here’s an example:

Consider rephrasing this double negative (“prevent” and “not in balance”) as a positive statement:

Instead of using negative requirements to indicate that certain functionality is out of scope, include the restriction in the Limitations and Exclusions section of the vision and scope document, as described in Chapter 5. If a specific requirement was once in scope but then removed, you don’t want to lose sight of it—it might come back someday. If you are maintaining requirements in a document, use strikethrough formatting to indicate a deleted requirement. The best way to handle such deleted requirements is with a requirements status attribute in a requirements management tool (see Chapter 27 for more about requirements attributes and status tracking).

We don’t know of any way to be certain that you’ve found every requirement. Chapter 7 suggests several ways to identify missing requirements. Focusing elicitation on user tasks rather than system features can help avoid overlooking functionality. Also, using analysis models can help you spot missing requirements (see Chapter 12).

Symmetry Symmetrical operations are a common source of missing requirements. I once found the following requirement in an SRS I was reviewing:

Nowhere in the rest of the specification did I find a requirement to allow the user to retrieve an incomplete but saved contract to work on it further: perhaps a requirement was missing. Nor was it clear whether the system should validate the data entries in the incomplete contract before saving it. An implied requirement? Developers need to know.

Complex logic Compound logical expressions often leave certain combinations of decision values undefined. Consider this requirement:

This requirement refers to two binary decisions, whose combinations lead to four possible outcomes. However, the specification only addressed this one combination. It didn’t say what should happen if:

The reader is forced to conclude that the system doesn’t take any action for those three other conditions. That might be correct, but it’s better to make such conclusions explicit rather than implicit. Use decision tables or decision trees to represent complex logic and ensure that you have not missed any variants.

Missing exceptions Each requirement that states how the system should work when everything is correct should also have accompanying requirements as necessary to describe how the system should respond when exceptions occur. Consider the following requirement:

This requirement alone does not indicate what the system should do if it’s unable to save the file with the same name. An appropriate second requirement to go with the first might be: