Six Tips for Writing Unambiguous Requirements

Karl Wiegers
Jan 10 · 6 min read

There’s a joke about the manager of a nuclear power plant who said the secret of running the plant safely is, “You can’t have too much heavy water.” Does this mean if you have too much heavy water you’re in trouble, or the more heavy water you have the better off you are? It could go either way.

Ambiguity is the great bugaboo of software requirements (and many other types of human communication). Ambiguity shows up in two forms. The first form I can catch myself, when I read a requirement and realize I can interpret it in more than one way. I don’t know which interpretation is correct, but at least I spotted the ambiguity.

The other type of ambiguity is much harder to detect. Suppose a business analyst hands a requirements document to several reviewers. They encounter an ambiguous requirement that makes sense to each of them but means something different to each of them. The reviewers all report back, “These requirements are fine.”

They didn’t find the ambiguity because each reviewer knows only his own interpretation of that requirement. Consequently, there’s a good chance that those reviewers will have different expectations and will take different actions because of their diverse understandings of that ambiguous requirement.

Here are six guidelines for writing requirements more precisely to avoid some of the pitfalls of ambiguous language. The examples are all drawn from actual requirements documents I’ve read.

Synonyms and Near-Synonyms

I once reviewed some requirements for software to control several analytical chemistry instruments in a laboratory. In some places the BA who wrote the requirements mentioned “chemical samples.” 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 it.

Whenever I read a document that uses slightly different terms to refer to the same item, I have to check with someone to determine whether they are truly synonyms. Elsewhere in that same requirements document the author had used three terms that I thought might be synonyms. When I inquired, though, I learned they had subtly different meanings.

Define such terms in a project glossary to help all readers reach the same understanding of the terms. The glossary is also a good place to decipher any acronyms or abbreviations used on the project.

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’s talking about.

Pronouns also can be a source of confusion in requirements. 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 item or action 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. Here’s an example:

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 requirement.

In this 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 they are from this requirement, so it could be incomplete as well as ambiguous.

Make it clear whether you’re presenting a complete list of items or just an illustrative subset. It’s clearer to explicitly say for example instead of e.g. so every reader knows what you mean. Latin isn’t many people’s native language these days.

A/B construct

Some requirement writers use what I call the A/B writing construct:

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

Is this requirement referring to an audit table, a history table, a history of audits, or an audit of histories? Or are both kinds of information stored in the same table? Or are audits the same as histories?

Other than input/output and read/write, the A/B construct is rarely used in formal writing because it’s so ambiguous. When I see that construct, I can think of five possible interpretations, but I don’t know which one is correct in the given situation:

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

Similar-Sounding Words

Writers sometimes use one word but mean another that sounds nearly the same. I’ve heard many BAs say, “I’ll flush out that requirement some more.” No, hunters flush their prey from a hiding place, but BAs flesh out their requirements to give them more substance. You home in on a solution, but you hone a dull tool. I see this kind of word usage error in news stories and other writing all the time.

Consider the following example, drawn from the requirements for a telephony product:

Phone Company 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 Phone Company caller tune for the same date, this will overwrite the Phone Company 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 can arise from mispronunciations in speech or if you’re not writing in your first language. Keep a dictionary handy so that you can be sure which word to use.

Adverbs

Words that end in -ly often are ambiguous. They might describe some desirable property of the product, but precisely what is desired is left to each reader’s interpretation. Following are some actual examples of ineffective adverb usage I’ve encountered:

  • 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 . . .
  • Generally incurs a “per unit” cost . . .
  • To enable remedial action to be initiated in a timely manner . . .
  • . . . as expediently as possible …

And here’s a double hit:

  • Occasionally (not very frequently) there will be an error condition . . .

Other adverbs to use with caution include: directly, easily, frequently, ideally, instantaneously, normally, optionally, periodically, preferably, rapidly, transparently, typically, and usually. Be specific when describing the intended product characteristics so all readers will share a common vision of what they’ll have when they’re done.

The Solution: Enlist Other Eyes

The paramount goal of writing any kind of requirements is: Clear and effective communication. Requirements quality is in the eye of the reader, not the author. No matter how fine the author thinks the requirements are, the ultimate judges are those who must base their own work on those requirements.

You won’t learn how to write good requirements just by reading books and articles. You need practice. Write requirements to the best of your ability, and then enlist some of your colleagues — including the downstream victims of your requirements — to review them. Constructive feedback from reviewers can help anyone become a better writer. In fact, it’s essential.

====================

This article is adapted from by Karl Wiegers. If you’re interested in software requirements, business analysis, project management, software quality, or consulting, provides numerous useful publications, downloads, and other resources.

The Startup

Medium's largest active publication, followed by +565K people. Follow to join our community.

Karl Wiegers

Written by

I’ve written on software development and management, consulting, self-help, chemistry, military history, and a mystery novel. More info at karlwiegers.com.

The Startup

Medium's largest active publication, followed by +565K people. Follow to join our community.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade