Eliminating Ambiguity from Your Requirements

Featured
22255 Views
9 Comments
23 Likes

From a developer's standpoint, few things are more frustrating than having to make lots of calls and research to learn what to create because the requirements are ambiguous. From an analyst's view, few things are more frustrating than having your requirements misunderstood. Yet so often, requirements are ambiguous to their readers, despite the writer's best efforts.

Everyone recognizes the importance of good requirements writing. DM Berry writes, "Software requirements specifications need to be precise and accurate, to be self-consistent, and to anticipate all possible contingencies."1 He also quotes Gause that one of the five leading sources of requirements failure is "too much unrecognized disambiguation." But in the diligence of gathering research, it can be easy for requirements writers to overlook details such as syntax and composition.

Yet as with any writing, poor composition, subjective thinking, and plain old bad grammar can cause confusion and bad assumptions. Incorporating a few simple habits into your writing will help eliminate ambiguity, ensure consistency, and help you to be understood.

Use active voice as much as possible. English teachers insist that using active voice make one's writing stronger. They are right, but it also makes one's writing clearer. Consider the following requirement: "The reports will be generated and the results will be displayed." The engineer is free to design a system in which the user manually generates a reports or the system automatically generates the reports. Either way, the engineer is meeting the requirement. Don't assume your reader knows who the actor is. Designating an actor in a sentence almost always results in greater sentence clarity: "The system will automatically generate the report, and the newly designed UI will display the results."

Watch for dangling participles. Few grammatical errors trigger misunderstood requirements like dangling participles. Consider the following sentence: "After attempting to generate for more than two minutes, the user will have the option to cancel the report." This requirement sounds as though the customer is attempting to generate the report for two minutes, when the writer's intent is to focus on the length of time it takes the report to generate. Correcting the dangling participle makes the requirement clearer: "After attempting to generate for more than two minutes, the system will offer the customer the option to cancel the report."

Clarify your pronouns. "The system will automatically generate the report, and the newly designed UI will display the results. It must be redesigned to accommodate the report." What must be redesigned, the system or the UI? Using "system" or "users" repeatedly rather than using "it" or "they" may make for more cumbersome reading, but it makes clearer requirements.

Specify your nouns. Do not use any noun that is subject to differing interpretations. "The user will be able to export a report once monthly when the system generates it." Who is the user? A customer, vendor, or office staff? Which system is the writer referring to--an existing system or a new one? Such clarifications only need to be made once, when the noun is first mentioned in your document, but they must be made. "The customer (referred to from here on as user) will be able to manually generate a report once monthly when our in-house supply software (referred to from here on as system) loads it." Also, clarify all acronyms and abbreviations when they're first mentioned.

Avoid would and should. Try to use will, shall, does, and has. Consider "The system will import all data," rather than "The system should import all data." Although it's unlikely that an engineer or developer will assume a requirement is optional because you used "should" instead of "shall", it's not what you truly mean. You don't mean that a requirement should happen. You're specifying that it will.

Use absolute modifiers for clarity. Using absolutes such as only, always, or limited to can change the entire meaning of your requirement:

The customer will be able to generate a report manually.

The customer will only be able to generate a report manually. [The customer will not be able to set the report to run automatically].

The customer will always be able to manually generate a manually. [This option will never be removed.]

If your requirement encompasses an absolute, include it.

Write to your audience. Don't assume that general readers know anything about what you're writing. If your readers are strictly developers, engineers, quality assurance personnel, and industry insiders, then industry jargon won't confuse anyone. But if customers or business people may review your requirements, avoid anything that your grandmother wouldn't understand. "The varchar field will be limited to 18,000 bytes per user specification," may confuse some readers. But most will understand: "Users can input up to 9,000 simple text characters (the maximum note size that any of our users have asked for)." If you must include a lot of industry jargon, consider including a glossary as an addendum.

Keep your sentences short and to the point. The fewer the words and the quicker your point, the lesser the chances of confusion. It's more difficult for a developer to interpret:

"The system will be designed to repeatedly generate the report once monthly automatically, and users will be able to generate more versions of the same report manually themselves a limitless number of times."

Than

"The system will generate the report once a month.

Users will be able to generate the report unlimited times."

Ensure that every requirement is written to be testable. Avoid subjective modifiers such as simply, efficient, or quickly. Make your requirement tangible, so that engineers know exactly what to build and quality assurance knows exactly what to test.

Not, "The system will allow the user to easily add a new order."

But "The system will allow the user to add a new order in five clicks or less."

Not, "The report will be generated quickly."

But "The report will generate in less than 10 seconds."

Run spelling and grammar check--a simple final step that can catch simple mistakes for you.

Ask for a peer review before you publish your document. After you write, read, and edit a document several times, objectivity becomes more difficult. Ask another analyst who is not familiar with your project to read your requirements, look for ambiguity and offer edits.

If you consciously incorporate some of these composition and grammatical habits to eliminate ambiguity from your requirements, over time they will become second nature to you, saving you time in your work and decreasing the number of revisions you make. You may find that your project cycle runs faster, your engineer/developer colleagues need fewer requirements clarifications, and your organization's processes running more smoothly.

Author: Morgan Masters is Business Analyst and Staff Writer at ModernAnalyst.com, the premier community and resource portal for business analysts. Business analysis resources such as articles, blogs, templates, forums, books, along with a thriving business analyst community can be found at http://www.ModernAnalyst.com


1 http://books.google.com/books?hl=en&lr=&id=LHvIXetZiFwC&oi=fnd&pg=PA7&dq=%22Berry%22+%22Ambiguity+in+requirements+specification%22+&ots=WyGZx1gIH-&sig=_HtSayl3k81zI1TPl6utXRyF7kk

Like this article:
  23 members liked this article
Featured
22255 Views
9 Comments
23 Likes

COMMENTS

sehlhorst posted on Friday, July 24, 2009 11:49 AM
This is a great topic - thanks, Morgan, for bubbling it back to the top - as evergreen content, it is important to remember. A couple other articles (that I wrote) that your readers may find helpful:

1. Looking at different types of ambiguity (ambiguous due to incompleteness, etc)
http://tynerblain.com/blog/2006/06/12/writing-unambiguous-requirements/

2. You must not write 'The System Shall...' (hot topic with 38 comments!)
http://tynerblain.com/blog/2009/04/22/dont-use-shall/

The second one focuses on language-barrier issues and looks at the translation of "shall" and "must" into other languages - surprising data there :).

Thanks again,
Scott
baldrick posted on Friday, July 24, 2009 2:46 PM
Agreed, this is a great topic. A few additional comments though:

1. "The system will automatically generate the report, and the newly designed UI will display the results." - If you are using the word 'and' in a requirement, you probably have 2 requirements or are stating the same requirement twice. In this case, stating that the system will display the results of the generated report, is sufficient.

2 - "After attempting to generate for more than two minutes, the system will offer the customer the option to cancel the report." - Can be simplified by stating that after 2 minutes the system will offer the option to cancel the report. Do not need to say what the system is doing for those 2 minutes.

3 - Using "system" or "users" repeatedly .. - This is an excellent point. One thing I teach my students is that requirements are not meant to make interesting reading .. use as few words as possible and if you have a choice of words that mean the same thing pick one and use it consistently.

If in doubt .. spell 'it' out. (I made that up.)

4 - Who is the user? A customer, vendor, or office staff? - The word 'user' should be defined prior to using it, as should all the actors.

5 - Which system is the writer referring to--an existing system or a new one? - Always group your requirements by system, so that there is absolutely no confusion.

6 - Try to use will, shall, does, and has. Consider "The system will import all data," rather than "The system should import all data."

In some areas of requirements writing these words have very specific meanings.
Will - A condition that exists today and will continue to exist after deployment.
Shall - A new requirement that will exist after deployment.
Should - A nice to have requirement that will not prevent deployment.

7 - Use absolute modifiers for clarity. - Disagree .. by using words like 'always' and 'only' you are effectively specifying what the system should NOT do. Requirements should always be written in a positive sense. Put yourself in the place of a tester. How do you write a test that verifies the systems will 'always' do something as opposed to the the system will?

8 - Write to your audience - Absolutely, that's why we have business requirements and system requirements.

9 - Avoid subjective modifiers - Avoid adverbs and adjectives, unless they have been explicitly defined in the glossary. For example, I can define 'slow' as being less than 1/10th maximum speed of the vehicle, then I do not have to keep spelling it out.

Finally, MODEL YOUR REQUIREMENTS. If the only language you have used to write your requirements is English, your requirements contain a lot of mistakes. Model the English text using a language such as UML, and then go back and update the text. Better still, if your audience understands UML, give them the model and throw the text away (yeah, like that has ever happened).

Hope this is useful.

Les.
businessanalyst.in.it posted on Tuesday, August 4, 2009 1:04 AM
Truly helpful is what I would simply say. Lots and lots of thanks to the Author and ModernAnalyst.com :). The briefing about reducing ambiguity by Keeping It Short and Simple (KISS) really addresses my concerns.

Thanks again
Sudhakar
jsanalyst posted on Tuesday, August 4, 2009 7:10 AM
excellent article...keep sharing
ymcdonald posted on Tuesday, August 4, 2009 8:46 AM
Good article. I was going to point out the same thing that Les pointed out in Step 2, but very good article.
DiThomo posted on Monday, August 10, 2009 5:38 PM
Thanks heaps! As a 'brand new" BA writing a very long and comprehensive Business Requirements do for the first time, this has been extremely helpful resource for me!
sajana posted on Thursday, September 17, 2009 1:07 AM
A very good article.
I have one question though...
Agreed, we need to follow these writing rules while writing requirement statements.
But do the same rules apply for use cases scenarios?

Example:
1. The system asks for username and password
2. The user enters username and password
3. The system verifies user credentials
4. The system displays the transaction page of the application with a welcome note to the user.

Do we need to rewrite the above statements as " The system will ask for username and password"


baldrick posted on Monday, September 21, 2009 9:26 PM
Do we need to rewrite the above statements as " The system will ask for username and password"

My suggestion is 'No'. Pick a style and be consistent.

Leslie.
sajana posted on Tuesday, September 22, 2009 11:53 PM
Thanks Les..
Only registered users may post comments.




Latest Articles

Six Estimation Safety Tips
Oct 13, 2019
0 Comments
Estimation is a chronically thorny issue for software practitioners. Most people need to prepare estimates for the work they do, but in our industry w...

Copyright 2006-2019 by Modern Analyst Media LLC