As Karl Wiegers accurately states in his paper on writing better requirements, “quality is in the eye of the reader … No matter how fine the author thinks the requirements are, the ultimate arbiters are those who must base their own work on those requirements.”
Avoiding ambiguity when writing requirements is essential to building the product you want built. In our recent post, “Five Ways Ambiguous Language Will Ruin Your Requirements,” we shared examples of ambiguity in requirements writing and gave expert tips to help clarify.
Here are four more sources of ambiguity, plus additional best practices to save your requirements — and your product.
Negative Requirements
Negative or inverse requirements create a lot of unnecessary ambiguity. Positive requirements in active voice are much easier to understand. Here are some before and after examples of increased clarity when moving from negative to positive.
Abbreviations i.e. and e.g.
Some readers might misconstrue the use of i.e. and e.g. 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 — either on the part of the writer or the reader — that they are best avoided altogether in favor of explicitly saying what you mean.
A/B Construct
Some requirements writers use the A/B construct, as in, “data should be recorded in an audit/history table.” This construct is rarely used in formal writing because it is so vague it could be interpreted in a variety of ways. Some examples include:
- A is the same as B. In this case, they are synonyms and you should stick to one term consistently.
- Both A and B. In this case, use the explicit conjunction “and.”
- A or B. In this case, use the explicit conjunction “or.”
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 a few examples:
- “Allows the user to edit his interests and possibly search results …” Should the user be able edit the search results or not?
- “Optimize upload and download to perform quickly.” Is five seconds considered quick?
- “Offer significantly better download times.” State exactly how much better or give a range for precisely what the download time should be.
- “Subscribers who are changing content selection (effectively a subset of the currently subscribed subscribers) …” Are they a subset or not?
- “Exposing information appropriately …” What’s considered appropriate?
Be specific when describing the intended product’s characteristics so all readers share a common vision of the desired result when they’re done.
Read Karl Wiegers’ paper, “Writing High-Quality Requirements,” to learn what else goes into crafting successful requirements.
The post How to Avoid Ambiguity and Save Your Requirements appeared first on Jama Software.
