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.

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!

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.

4 thoughts on “Writing Unambiguous Requirements”

Audience ambiguity comes from different readers interpreting the language differently. You and the Seilevel folks have cited the famous Gause and Weinberg of “Mary had a little lamb.” Does it mean she kept one as a pet? Does it mean she gave birth to one? Or something else?

Conceptual ambiguity is independent of the audience. It is function of the logical structure of the statement. “The system shall be fast” is conceptually ambiguous, because speed is a matter of degree, and the statement contains no constraint on it.

The reason for writing requirements that are testable in principle is to prevent conceptual ambiguity. I just wrote about it in today’s blog entry.

Oops, a bit of ambiguity straight away with “MRD”, an undefined term :-) I can take a stab at R and D, but no ideas on M… I’ll check acronym buster. I predict if I have to write an MRD it’ll be about an hour before I start calling it a “merde”!

Product Management Today

@sehlhorst on Twitter

Who Should Read Tyner Blain?

These articles are written primarily for product managers. Everyone trying to create great products can find something of use to them here. Hopefully they are helping you with thinking, doing, and learning. Welcome aboard!