Avoid ambiguity when writing requirements for software purchases

Adequate and well-written requirements are the foundation for selecting enterprise software that meets expectations. A common problem with requirements is that some of them may be ambiguous. While ambiguities are easy to see in requirements written by others, they are difficult to spot in your own writing. Ambiguities cause problems selecting software in cases such as these:

• Vendors responding to RFIs or RFPs: When vendors have to make assumptions about ambiguous requirements, they are entitled to (and will) interpret requirements in the way most favorable to their products.
• Implementing software: When consultants implementing the software make assumptions, they may not configure software in the way users expect, and this can cause business disruption when going live in production.

Let’s start by defining what is meant by ambiguous requirements:

• A single reader can interpret a requirement in more than one way and is unsure which is the intended interpretation.
• Several readers can interpret a requirement differently from one another.

Ambiguities are difficult for writers to see because, when they’re writing requirements, they have a particular context in mind. The ambiguity is only visible to somebody who does not have this context. That is why writers may be able to see ambiguities if they reread their requirements after a few weeks, because they have forgotten the assumed context.

We were working with a client team weighting requirements for their organization when we came across one incomprehensible requirement. The name of the author was on the requirement, and he was in the meeting. When asked to explain, he said, “I have no idea of what I meant!” We ended up deleting it from the list because it had no meaning for that project. He simply could not remember what he was thinking of when he wrote it.

A well-written requirement has a single reasonable interpretation in a given context, and that context is part of the requirement, as in an example. Some factors that cause requirement ambiguities are:

• A context is assumed, but not all readers will know that context.
• The requirement is written at too high a level. For example: “The software shall be easy to use.”
• An incompletely written requirement, or one that is not explicit enough.
• Poorly structured requirements. For example, having unclear antecedents, being written in the negative, using often confusing terms or abbreviations.

How to write unambiguous requirements

Use examples

Examples are one of the most powerful ways of removing ambiguities because they provide the context in which to understand a requirement. Include one or more examples of how features that satisfy a requirement might be used by the organization. Also, you can include examples of how features satisfying the requirement could be implemented by a software vendor.

Be explicit

Minimize the use of assumptions, because assumptions invite misinterpretation. Instead, explicitly state what is being assumed, and do not worry about being repetitive. You are not writing a novel, and your writing does not have to be “interesting”!

Bridgestone Tires took IBM to court for a failed ERP implementation. Imagine you were in a similar situation and the outcome of your case depended on whether you could show the software vendor had misrepresented what its product could do. The more explicit the requirements, the better the odds you would have a favorable judgment. Keep this in mind when writing or editing requirements.

Avoid adverbs

Adverbs are subjective and result in ambiguity when people interpret them differently. For example “The system must refresh the data reasonably quickly” is vague because the word reasonably is ambiguous. If it used to take a vendor 8 hours of computing to refresh the data, and now they do it in 10 minutes, is that reasonable when the organization wants a real-time response? If an organization wants real-time responses, it must specify that explicitly. For example: “The system must refresh the data within 0.5 seconds.” It is also helpful to say why such a fast response is desired. For example, the reason could be “because customers are on the phone.” Avoid adverbs like generally, usually, normally, frequently, occasionally and so on when writing requirements.

Be careful with pronouns

A pronoun refers to a previously used noun, and that noun is called the antecedent. Pronouns can be ambiguous when their antecedents are unclear. Here’s an example of a requirement with a pronoun whose antecedent is unclear: “When in a date field, the user should be able to open a pop-up calendar. This allows the user to…” What is the this that allows the user to do something? It could be the date field or the calendar. Unclear antecedents introduce ambiguities. That requirement could be rewritten like this: “When in a date field, the user should be able to open a pop-up calendar which allows the user to …” I have found that tools like Grammarly can be very good at catching unclear antecedent errors.

When writing requirements, write “the user” rather than “you” because there is less opportunity for confusion. For example, “The user should be able to…” rather than “You should be able to…”

Use consistent terms

Do not be creative and vary your writing to keep reader interest. Avoid ambiguity by using terms and phrases consistently throughout the requirements. If the requirements use several similar but not identical terms, create a glossary so readers can see exactly what those terms mean.

Avoid negative requirements

Negative requirements say what the system should not do, rather than saying what it should do. For example, if the requirement stated “The system should not allow external users to access…” does that mean that consultants working on-site get access or not? The requirement is better phrased as “The system will only allow employees to access…” Note that the word only is what creates the limitation. Avoid double negatives, which are even more ambiguous.

Avoid confusing abbreviations

The abbreviations e.g. and i.e. are often confused. While e.g. means “for example” and will be followed by one or more illustrations that clarify a concept, i.e. means “that is” and should be followed by a complete list of items. To avoid confusion, use the full English words.

In British English, the abbreviation nb is very common. It means “note well.” Most Americans are not familiar with nb at all, and simply use the word note. Avoid using the nb abbreviation.

How to find ambiguous requirements

One useful technique is to reread your requirements after two or three weeks. By then you will have forgotten some of the contexts and will be able to see the ambiguities. Another technique is to ask co-workers to read them. Finally, when teams meet to weight requirements for importance to the organization, team members will often see ambiguities, which can then be corrected before vendor responses are solicited.

Wrap up

Ambiguous requirements can cause unexpected and unnecessary problems when acquiring enterprise software. As a software purchaser, it is your responsibility to craft “well-written” requirements that avoid ambiguities. By following these guidelines, you can reduce the ambiguities in your requirement writing, which helps ensure the new software will meet organizational expectations.