Requirements & Requirements Management

Elements of Requirements Style, Part 4

By |

Ambiguity is one of the biggest problems I see with requirements specifications written (as they all are) in natural language. There is no end to ways that people can miscommunicate through the written word. The business analyst’s goal is to try to make the meaning of each requirement as precise and clear as possible, aiming for just one possible interpretation of each. In this final article in the series, I offer some guidelines for writing requirements more precisely to avoid some of the pitfalls of ambiguous language.

Synonyms

I once reviewed some requirements for software that controlled several analytical chemistry instruments in a laboratory. In some places, the analyst who wrote the specification referred to “chemical samples,” and in other places she referred to “runs.” I asked her about the difference between a sample and a run. “They’re really the same thing,” she replied. I suggested she pick one term and stick to her story. Whenever I read a document that uses slightly different terms to refer to the same item, I have to check with someone to ascertain whether they are truly synonyms. Place such definitions in a shared glossary so that team members can use them consistently throughout the project and perhaps even across multiple projects.

Elsewhere in that same SRS the author had used three terms that I thought might be synonyms. When I inquired, I learned that they had subtly different meanings. Define such terms in your project glossary to ensure that all readers can reach the same understanding of the terms.

Pronouns

My mother is a known pronoun abuser. She will say something like, “He said he’d bring that down as soon as he was done with it,” and I’ll have no idea who or what she is talking about. Pronouns also can be a source of confusion in a requirements specification. Be certain that the antecedent is crystal clear whenever you employ a pronoun. If you use a word such as this or that, there should be no confusion in the reader’s mind about what you’re referring to.

The abbreviations i.e. and e.g.

Another ambiguity risk involves using abbreviations that some readers might misconstrue. A common point of confusion is the use of i.e.  versus e.g. Consider the following requirement from an actual specification:

The program needs to have a means of allowing the operator to manually activate certain portions of the process in the event a mistake is made (i.e., activate the valve set to apply pressure or vacuum, set pressures, and activate the temperature chamber).

The abbreviation i.e. stands for the Latin phrase id est, which means “that is.” The abbreviation e.g. stands for the Latin phrase exempli gratia, which means “for example.” These two abbreviations are so commonly confused that I don’t trust their use in a requirements specification unless I’m positive that the author understands the difference. In the previous example, the use of i.e. indicates that the following list itemizes all portions of the process that require a means of manual activation. However, if the author really meant for these to be just examples—a portion of that set—he should have used e.g. instead. That way, the reader knows that many more such manual activations could be needed. Unfortunately, the reader won’t have any idea how many more activations might be needed or just what those activations are from this requirement. It’s essential to make it clear whether you are presenting a complete list of items or just an illustrative subset. I suggest explicitly saying for example instead of e.g. so every reader knows what you mean.

A/B

Some specification writers use an A/B writing construct, as in the following example:

Prior to operator intervention, a snapshot of this data should be recorded in an audit/history table.

What exactly does this mean? Is this requirement referring to an audit table, a history table, a history of audits, or an audit of histories? Are both kinds of information stored in the same table, or are audits the same as histories, or what? Other than and/or, read/write, and a few others, the A/B construct is rarely used in formal writing because it is so ambiguous. When I see that construct, I can think of five possible interpretations, but I don’t know which one is correct in a given situation:

  • A is the same as B. (If A and B are synonyms, use just one term consistently.)
  • Both A and B. (Use the explicit conjunction and.)
  • A or B. (Use the explicit conjunction or.)
  • A is the opposite of B, as in “approving/disapproving changes.” (Use the conjunctions and and or as appropriate to convey the correct meaning.)
  • “I’m not sure just what I’m thinking here, so I’ll leave it up to each reader to decide what he thinks this means.” (Decide exactly what you intend to say, and choose the right words.)

Similar-Sounding Words

Writers sometimes write one word but mean another. As an illustration, I often hear people say, “I’ll flush out that specification some more,” when they really mean, “I’ll flesh out that specification some more.” Hunters flush their prey from their hiding places, but analysts flesh out their requirements to give them more substance. And consider the following example, drawn from an actual SRS for a telephony product:

Special Day caller tunes (default) will take priority over all configured individual caller settings that a customer has selected. However, if an individual has been assigned a Special Day caller tune for the same date, this will overwrite the Special Day caller tune.

You overwrite a piece of data, but you override a default value. In this context, either interpretation is potentially correct, so it’s imperative that the author chooses the right word. Watch out for these common types of errors, which sometimes arise from mispronunciations in speech. Keep a dictionary handy so that you can be sure which word to use. A useful reference for common word usage errors in English is provided by Paul Brians at http://www.wsu.edu/~brians/errors/errors.html.

Adverbs

Words that end in -ly often are ambiguous. They might describe some desirable property of the product, but exactly what is desired is left to each reader’s interpretation. Here are some real examples of ineffective adverb usage in requirements specifications:

  • Provide a reasonably predictable end-user experience.
  • Offer significantly better download times.
  • Optimize upload and download to perform quickly.
  • Performance for these users should broadly match those for…
  • Downloading this file should complete in approximately 15 minutes.
  • Exposing information appropriately…
  • Allows the user to edit his interests and possibly search results…
  • Request formats sent by customers must be clearly defined.
  • Subscribers who are changing content selection (effectively a subset of the currently subscribed subscribers)…
  • Generally incurs a “per unit” cost…
  • To enable remedial action to be initiated in a timely manner…
  • …as expediently as possible…
  • Occasionally (not very frequently) there will be an error condition…

Some other adverbs to use with caution are directly, easily, frequently, ideally, instantaneously, normally, optionally, periodically, preferably, rapidly, transparently, typically, and usually. Try to be more specific when describing the intended product characteristics so that all readers will share a common vision of what result they will have when they’re done.

You won’t learn how to write good requirements from reading a book on software requirements engineering or a book on technical writing. You need practice. Write requirements to the best of your ability, and then enlist some of your colleagues to review them. Constructive feedback from reviewers can help anyone become a better writer. In fact, it’s essential. Requirements quality is in the eye of the reader of the requirements, not the author. No matter how fine the author thinks the requirements are, the ultimate arbiters are those who must base their own work on those requirements.

Also read Elements of Requirements Style, Part 1

Also read Elements of Requirements Style, Part 2

Also read Elements of Requirements Style, Part 3

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)