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