Writing Unambiguous Requirements

One of the ten big rules of writing a good MRD is writing unambiguous requirements. Ambiguity is a function of communication. The writing can be generically ambiguous, or ambiguous to the writer. A requirement could be precise in intent, but ambiguous in interpretation by the reader. Understanding our audience is as important as precision in language. We write unambiguous requirements because misinterpretation of requirements is the source of 40% of all bugs in delivered software.

The Big Rule of Writing Unambiguous Requirements

From our previous article, Writing Good Requirements – Big Ten Rules:

A great requirement has a single interpretation. A good requirement has a single reasonable interpretation. As part of our development process, we will use listening skills like active listening to make sure that our engineering team understands the requirement we intended to write. The better the requirements, the less expensive and risky this communication process will be. Writing unambiguously is critically important when using outsourcing models that limit our interactions with other team members.

Ambiguous to the Writer

We introduce ambiguity with imprecise language. Using shall instead of should is one of the first things people suggest (or require!) when writing requirements. [Added 2010.08.17 – shall is ambiguous too – use must!] Red flags are also raised with words like can and might. Marcus wrote a good post about vague requirements language

What do the terms: user-friendly, flexible, easy-to-use, fast, and intuitive mean to you? Do you think these terms mean the same thing to someone else? Generally, no!

from Speculative and Vague Terms

These are examples where the language is ambiguous, both to the writer and the reader. Any uninformed third party could read these requirements and identify the amiguity in the language. This makes these mistakes easy to catch – all that is required is a good working knowledge of the language.

Ambiguous to the Reader

Even precisely written, grammatically correct prose can be ambiguous to the reader. This ambiguity can come either from lack of expertice with the language, or from incompleteness of the requirement.

Language Ambiguity

With the ever-increasing outsourcing of teams, we have to think about writing requirements for outsourced team members. When we use a complete technical outsourcing model, we have to consider the possibility (or certainty in some cases) that the primary language of the readers of the MRD is not the language it is written in. Making a document easy to read (short sentences, common words) can be at odds with making the language of the requirements precise.

Some good research on vocabulary size data for comprehension of english can be found here. The average native english speaker knows 20,000 word families. With a vocabulary of 5,000 english words, only 98.5% of the words in a given text will be understood. 5,000 words is a lot for a speaker of a second language (3,000 words is considered a working knowledge).

An analysis of the reading-level at which a document is written can be helpfull in identifying if the language is likely to be challenging for readers with limited vocabularies. The Gunning-Fog Index provides a measure of the education level at which a text is written.

Incompleteness Ambiguity

When the language is both precise and understood, we still face challenges in ambiguity by failing to provide all the information. When we find ourselves wanting to say “That was implied, you should have known that!”, we are still being ambiguous. Clarity exists not only in language but in intent. Should the reader assume that when we specified user-authentication and role-based functionality that we intended users to have roles? If we specify that the best-matching search results must be presented within 1 second, is it ok if the rest of the results are presented later? And how many of the best-matches must be found?

Writing requirements like this is definitely a risk, and probably ambiguous. If we have a history, a rapport, and synchronous feedback cycles with the readers of the document, this may not be vague. We may be able to rely on them to assume the same things we assume. The language in the document may be serving effectively as shorthand for this communication. If we are working as a team with a shorter history of working together, this almost certainly will not communicate what we intended. There is also a risk of going too far.

Conclusion

Writing unambiguous requirements requires us to write complete requirements. It also requires us to use precise language that communicates information across domains to our readers. To determine the right level of effort, we need to monitor the effectiveness of our communication, and balance that with the amount of time we can afford to dedicate to word-smithing instead of other product management activities.