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.

image of feet of two people dancing the tango

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?

image of someone writing

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.

woman reading

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

  • Scott Sehlhorst

    Scott Sehlhorst is a product management and strategy consultant with over 30 years of experience in engineering, software development, and business. Scott founded Tyner Blain in 2005 to focus on helping companies, teams, and product managers build better products. Follow him on LinkedIn, and connect to see how Scott can help your organization.

34 thoughts on “Writing Unambiguous Requirements

  1. Thanks Scott for another great article. This is one of those subjects that I constantly have to remind myself about, because even though I fix it today, I’ve noticed that the greyness returns to my requirements without constant attention. I appreciate you taking the time to keep me, and the rest of the analyst world, straight.

    Doug

  2. Thanks, Doug!

    For everyone else, I’ve removed the “rate this article” feature from the blog as more and more folks shift how they share “low barrier to entry” feedback from the old model (clicking on stars to rate articles) to the new model(tweet a link to an article).

    One of the goals for the Tyner Blain blog is to foster community – both helping me to discover and interact with the great folks out there who share my love of building the right thing right, and to help you connect with each other.

    The previous star rating system provided me with (limited) feedback on the quality of articles. But that communication was primarily many-to-one, and limited in utility. Moving to a “tweet this if you like it” model provides the same benefit to me, but also creates opportunities for you to discover each other – a many-to-many feedback model.

    When you read an article here that you like, not only can you let me know that you like it (by sharing it on Twitter), but you can also discover other people who liked it by seeing their tweets in the comments section of the article. You can then choose to follow those people on Twitter, and you will immediately be exposed to other articles that they like (and tweet) – making your world passively better. You can also engage in conversation with those folks – making your world actively better.

    Sorry for the off-topic comment, but it didn’t seem worth an entire article, so what better place to write it than in the comments?

  3. Also – I’m not sure if I wrote this “out loud” yet, but one reason for revisiting this series of articles now is to make them better in preparation for pulling them together into a cohesive work.

    The best way to make them better is to engage in conversation with all of you, not just to add the “what I’ve learned in the last four years” bits.

    So….

    When this article becomes a section of something larger (maybe next year) – how should I make it better?

  4. Pingback: Roger L. Cauvin
  5. Pingback: Yama
  6. Pingback: doug goldberg
  7. Pingback: Therese
  8. Pingback: Julie Hunt
  9. Pingback: david hudson
  10. Pingback: AppShows.com
  11. Pingback: Scott Willeke
  12. Pingback: Adrian Logan
  13. Pingback: April Dunford
  14. Pingback: Aldon ALM Software
  15. Pingback: Julie
  16. Pingback: Alltop Agile
  17. Great post. I loved the specific examples- very actionable advice!

    I’d add the following:
    Words are connotational, not denotational. That is, there meaning is tied to other meanings and context in very subtle and not-so subtle ways.

    For instance, in any company that does product development the meaning of the word product changes per department (merchandising, design, development, testing, sourcing, manufacturing, support) or per lifecycle stage (ideation, development, sourcing, testing, commercialization, etc) or combination of both.

    And all these departments use the word “product”. Ouch!

    Or even better, when making changes when is that product no longer that product? Some companies use form/fit/function- if it’s the same, it’s the same product. But if a purchased component would it it still be the same product if from different vendors?

    Often, from a design perspective, yes. From a manufacturing and quality perspective, no.

    I’ve seen arguments rage for hours, and then repeat every few weeks, all due to this issue.

    So to get clear requirements adding to the language is often critical. I often joke “never use one word when two will do”. Obviously not always the case, but the nature of language and business often require this to gain require precision in requirements.

    1. Thanks, Nick, and welcome to Tyner Blain!

      One of professor Berry’s arguments about language ambiguity is that the problem with anaphors (pronouns) is that they require context to determine what it is to which they are referring. [I used extra words there, just for you :)] His point was narrowed to the immediate grammatical context – did the pronoun refer to something earlier in the sentence (the monkey or the banana), something in the previous sentence, or something in the previous paragraph?!

      Your point is also extremely valid – even nouns have varied meaning depending on the domain context in which they are used. Luckily, there are a good techniques for addressing this particular problem within a requirements document – create a glossary, a data dictionary, or create a fact model. Creating a reference within your deliverable(s) that provides a precise definition of the contextual interpretation of any given term, for the purposes of the requirements document definitely helps.

      I’ve seen fact models that I created (for a requirements document) get extended to become the local jargon decoders for a group. People on the teams appreciated the value of clarity from the fact model so much that they adopted it as a standalone artifact, to which future requirements documents were required to refer.

      Perhaps it is time for another article. I’ve been using fact models since I first heard about them from Ron Ross at IBRF in 2007, and they are awesome. Fact models are artifacts that come from the business rules community, and I’ve found that fact models are just as powerful in the requirements world.

      Thanks again!

  18. Spot on! Two additional points:

    [1] As the writer, you may lack knowledge that your readers (developers) have, and therefore be ambiguous. In a recent requirements doc of mine, I referred to the customer’s service level (bronze, silver, gold) but didn’t know that we have some other modifiers. The dev team knew about some overlay features (bronze with auth-upgrade allowed, bronze without…) that changed the requirements. I had to do more research to be less ambiguous.

    [2] Clarity is in the eyes of the reader. If your dev team doesn’t understand what you’ve written, then [by definition] it’s not clear enough. This isn’t an abstraction: ask the group several times where you’re unclear or short on details. Review the doc carefully with your team. And in return, you should be reading the functional specs (or other dev docs) that map out the solution to your problem. If you don’t understand them, then demand some clarity of your own.

    1. Thanks, Rich!

      Great additions. I’d definitely call out “oversimplification” as a source of ambiguity, as you describe. Sort of like saying “Must work on a cellphone” – well, that’s way too inspecific and ambiguous. Fantastic catch.

      Your point #2 properly re-emphasizes the need for active listening. I should have expanded on that, instead of just including a link in the conclusion of the article. This is a big deal that far too many product managers / product owners overlook. Often people fail to understand this because they either come from a technical background (so assume they know), or from a non-technical background (so assume they don’t need to know).

      Thanks again!

  19. Pingback: Julian Sammy
  20. Pingback: Ashraf Ansari
  21. Pingback: David Smith
  22. Pingback: Clive Seebregts
  23. Pingback: Eric Provost
  24. Pingback: Mary B. Gorman
  25. Pingback: Jennifer Banzon
  26. Pingback: cindyalvarez
  27. Pingback: Pranav Desai
  28. Pingback: Kevin Rochowski
  29. Pingback: Seilevel
  30. Pingback: Ioana Nicolaescu

Leave a Reply to DougGtheBA Cancel reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.