Writing Unambiguous Requirements

Writing unambiguous requirements is about understanding what is written, and what is read. Without a clear understanding of your market, you can’t write unambiguously. Even when you understand your market, you risk writing something that is ambiguous to your readers. Documenting requirements is about communication. Don’t break this rule, or you’ve wasted all the energy you spent understanding your requirements.

Unambiguous Requirements – Revisiting

Fifty months and five days ago (another grin), I wrote about the importance of writing requirements so that they can be clearly understood. Writing requirements so that there is one, unambiguous, interpretation of what you wrote. This article is the seventh in a series on the rules of writing good requirements. In that version of the article, I focused primarily on language ambiguity, and framed the discussion in terms of ambiguity to the writer and to the reader.

As part of improving that series, I am revisiting each of the articles now that I have fewer hairs and the remaining ones are more gray. The same framework still applies, but will be expanded in scope, using the following modified definitions of the framework.

• Ambiguity for the Writer – not having a clear interpretation of the requirements.
• Ambiguity for the Reader – requirements that, as written, can be interpreted in more than one way.

It takes two to tango. To lead, you have to know where you’re going. To follow, you have to know where you’re being led. The same is true with requirements – you have to know what you’re writing, and how your writing will be read. Misinterpretation of requirements is the source of over 40% of all software defects.

Ambiguity for the Writer

When you don’t know why you’re developing a particular set of requirements, it is because you either don’t have sufficient understanding of your market, or of your corporate objectives. While it is always a lack of knowledge, sometimes, that lack of understanding is insidiously hidden. You, as the writer of requirements, are the reader of the market – and what you’re reading is likely to be ambiguous.

For Whom You Are Designing

The most overlooked element I’ve personally seen in product creation is failing to understand who the users and buyers of your product will be. I wanted to type “forgetting to understand,” but I struggle to imagine someone who understands the value of defining user personas and buyer personas, who then forgets to define them when gaining an understanding of their market.

The reason that this is an ambiguity issue is that when you fail to define personas explicitly, you define them implicitly. An implicit persona is an ambiguous persona. Alan Cooper named this anti-pattern the elastic user, and the problem manifestation as failing to provide insight to guide design decisions. When you have an ambiguous user, you lose what Frederick Brookes calls the clarity of design. This results in at best a mediocre product without a core idea or aesthetic.

Different users value the same solutions differently. Users vary in competency, and therefore have varied personal goals as they learn how to better use your product over time. When you don’t identify who the user is, you prioritize requirements without insight into what is important to the undefined, elastic, and ambiguous user.

The readers of your requirements are trusting that you will prioritize requirements correctly – but you can’t, because you lack an understanding of who the users will be. You therefore lack an understanding of which problems are valuable, and which problems are more or less valuable than other problems. This ambiguity makes it particularly difficult to write valuable requirements.

Precision in Language

The other aspect of writing unambiguously is in using language that has meaning. Using words like “can” and “may,” is imprecise in requirements. “The system can respond in under three seconds.” Does that mean that it must respond in under three seconds? Does that mean it is acceptable if the system responds in twenty seconds? This is an area of overlap with the rule of writing measurable, verifiable requirements, so I won’t go into more details here.

Another source of imprecision in language, not only for the reader, but also for the writer, is jargon. You should never use jargon, as you have no way to know if your reader will actually interpret the jargon terms correctly – as readers often vary in the depth of their domain knowledge. Jargon is also a high risk of ambiguity source, precisely because it is jargon. Jargon is short-hand for communicating efficiently among domain experts. Are you enough of a domain expert that you are confident that you absolutely, unambiguously understand the accepted meaning of the jargon term?

Hopefully, you’ve achieved a perfect understanding of your market. Long-time readers will know that I’m joking. Market analysis suffers from it’s own Heisenberg Uncertainty Principle – if you actually did manage a perfect understanding, the market will have changed – the best you can hope for is a statistical understanding of the behavior of your market. You can document your interpretations, assumptions, and decisions – achieving clarity in your requirements – at least from your point of view.

Ambiguity for the Readers

As I mentioned earlier – using requirements is a dance – and it takes two, both the writer and the reader. You need to write requirements so that they can only be interpreted in a single way, or you will stumble.

“You keep using that word. I do not think it means what you think it means.” – Inigo Montoya (IMDB)

Shared Language

The word “shall” as in “the system shall…” can be misinterpreted when your readers don’t share the same native language as you – which is why you must always use “must.“

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

Writing Unambiguous Requirements (2006)

Can’t write that section any better :).

Ambiguous Use of Language

I had the privilege to attend a presentation by professor Daniel M. Berry in 2007, on the ambiguous use of language in business rules and requirements. In that presentation he referenced The Ambiguity Handbook that he authored (80 page pdf), which I just re-read last week. There are many good examples of ambiguity in the use of English in business documents.

The following are some of the sources of ambiguity, for which I entirely credit professor Berry for pointing out to me. I’ve only added some illustrative examples:

• Plurality Causes Ambiguity. Consider “Emails must include sender addresses” and “emails must include recipient addresses.” Must each email include one sender address and one recipient address? Must each email include multiple sender addresses? Solution – don’t use plural subjects. “Each email must include a sender address” and “each email must include recipient addresses.”
• Associative Ambiguity. Professor Berry calls this the parenthesis problem. What does “A and B or C” mean to you? Does it mean “A, and either of B or C” or does it mean “either C, or both A and B” when you read it? In math and programming, we learn very specific rules for how to interpret these types of structures. We are also given parentheses, that we can use when we want to be specific and unambiguous. The reader of your requirements is not a compiler, so don’t assume that she will interpret this the same way that you do. Solution – use parentheses and explicit language to eliminate ambiguity that would arise from ignorance of the associative property.
• Anaphor Ambiguity. For non-linguists: “don’t use pronouns.” I love the example that wikipedia uses – “We gave the bananas to the monkeys because they were hungry. We gave the bananas to the monkeys because they were ripe.
  
  We gave the bananas to the monkeys because they were here.” The pronoun, “they,” has an ambiguous binding. Should “they” be a reference to the bananas or the monkeys? In each of the first two sentences, you could reasonably assume that the reader will properly bind “they” to the monkeys and bananas respectively. In the third sentence, an assumption of how the reader will interpret “they” is not reasonable. Reasonable assumptions are still ambiguous – and the context is less likely to be obvious – so don’t use pronouns and rely on readers to bind them to the appropriate nouns. Solution – repeat the noun for every reference.

Incompleteness Ambiguity

Unwritten requirements are by definition ambiguous. You must not assume that unstated requirements will be implemented.

A security exploit was recently discovered (and eliminated) in Facebook. Previously, if you attempted to login to Facebook with an email address and a password that did not match the email address, Facebook would present you with a typical “failed login” screen and a link to reset your password. However, in an effort to be friendly, Facebook would also include the first name and last name that were associated with that email account in the friendly warning message.

That is nice, except it is a privacy problem, and anyone who knew about this before could use the login page to discover the first and last name to associate with any email address. “Bad people” with email address lists could discover the name to associate with many of those email addresses – allowing more sophisticated phishing or social engineering attacks.

The requirement to not provide any personal information when a user fails a login attempt was almost certainly an unwritten requirement.

Conclusion

Precision in your writing will reduce ambiguity in your requirements. Active listening will help you discover when ambiguity has slipped through your editing net. You can never completely eliminate this problem, but you can improve. You must.