Ambiguity is one of the biggest problems I see with requirements specifications written (as they all are) in natural language. There is no end to ways that people can miscommunicate through the written word. The business analyst\u2019s goal is to try to make the meaning of each requirement as precise and clear as possible, aiming for just one possible interpretation of each. In this final article in the series, I offer some guidelines for writing requirements more precisely to avoid some of the pitfalls of ambiguous language.<\/p>\n
I once reviewed some requirements for software that controlled several analytical chemistry instruments in a laboratory. In some places, the analyst who wrote the specification referred to \u201cchemical samples,\u201d and in other places she referred to \u201cruns.\u201d I asked her about the difference between a sample and a run. \u201cThey\u2019re really the same thing,\u201d she replied. I suggested she pick one term and stick to her story. Whenever I read a document that uses slightly different terms to refer to the same item, I have to check with someone to ascertain whether they are truly synonyms. Place such definitions in a shared glossary so that team members can use them consistently throughout the project and perhaps even across multiple projects.<\/p>\n
Elsewhere in that same SRS the author had used three terms that I thought might be synonyms. When I inquired, I learned that they had subtly different meanings. Define such terms in your project glossary to ensure that all readers can reach the same understanding of the terms.<\/p>\n
My mother is a known pronoun abuser. She will say something like, \u201cHe said he\u2019d bring that down as soon as he was done with it,\u201d and I\u2019ll have no idea who or what she is talking about. Pronouns also can be a source of confusion in a requirements specification. Be certain that the antecedent is crystal clear whenever you employ a pronoun. If you use a word such as this<\/i> or that<\/i>, there should be no confusion in the reader\u2019s mind about what you\u2019re referring to.<\/p>\nThe abbreviations i.e. and e.g.<\/h2>\n
Another ambiguity risk involves using abbreviations that some readers might misconstrue. A common point of confusion is the use of i.e.<\/i>\u00a0 versus e.g.<\/i> Consider the following requirement from an actual specification:<\/p>\n
The program needs to have a means of allowing the operator to manually activate certain portions of the process in the event a mistake is made (i.e., activate the valve set to apply pressure or vacuum, set pressures, and activate the temperature chamber).<\/p>\n
The abbreviation i.e.<\/i> stands for the Latin phrase id est<\/i>, which means \u201cthat is.\u201d The abbreviation e.g. <\/i>stands for the Latin phrase exempli gratia<\/i>, which means \u201cfor example.\u201d These two abbreviations are so commonly confused that I don\u2019t trust their use in a requirements specification unless I\u2019m positive that the author understands the difference. In the previous example, the use of i.e.<\/i> indicates that the following list itemizes all<\/i> portions of the process that require a means of manual activation. However, if the author really meant for these to be just examples\u2014a portion of that set\u2014he should have used e.g.<\/i> instead. That way, the reader knows that many more such manual activations could be needed. Unfortunately, the reader won\u2019t have any idea how many more activations might be needed or just what those activations are from this requirement. It\u2019s essential to make it clear whether you are presenting a complete list of items or just an illustrative subset. I suggest explicitly saying for example<\/i> instead of e.g.<\/i> so every reader knows what you mean.<\/i><\/p>\nA\/B<\/h2>\n
Some specification writers use an A\/B writing construct, as in the following example:<\/p>\n
Prior to operator intervention, a snapshot of this data should be recorded in an audit\/history table.<\/p>\n
What exactly does this mean? Is this requirement referring to an audit table, a history table, a history of audits, or an audit of histories? Are both kinds of information stored in the same table, or are audits the same as histories, or what? Other than and\/or<\/i>, read\/write<\/i>, and a few others, the A\/B construct is rarely used in formal writing because it is so ambiguous. When I see that construct, I can think of five possible interpretations, but I don\u2019t know which one is correct in a given situation:<\/p>\n Writers sometimes write one word but mean another. As an illustration, I often hear people say, \u201cI\u2019ll flush out that specification some more,\u201d when they really mean, \u201cI\u2019ll flesh out that specification some more.\u201d Hunters flush<\/i> their prey from their hiding places, but analysts flesh<\/i> out their requirements to give them more substance. And consider the following example, drawn from an actual SRS for a telephony product:<\/p>\n Special Day caller tunes (default) will take priority over all configured individual caller settings that a customer has selected. However, if an individual has been assigned a Special Day caller tune for the same date, this will overwrite the Special Day caller tune.<\/p>\n You overwrite<\/i> a piece of data, but you override<\/i> a default value. In this context, either interpretation is potentially correct, so it\u2019s imperative that the author chooses the right word. Watch out for these common types of errors, which sometimes arise from mispronunciations in speech. Keep a dictionary handy so that you can be sure which word to use. A useful reference for common word usage errors in English is provided by Paul Brians at http:\/\/www.wsu.edu\/~brians\/errors\/errors.html<\/i>.<\/p>\n Words that end in -ly<\/i> often are ambiguous. They might describe some desirable property of the product, but exactly what is desired is left to each reader\u2019s interpretation. Here are some real examples of ineffective adverb usage in requirements specifications:<\/p>\n Some other adverbs to use with caution are directly, easily, frequently, ideally, instantaneously, normally, optionally, periodically, preferably, rapidly, transparently, typically, <\/i>and usually<\/i>. Try to be more specific when describing the intended product characteristics so that all readers will share a common vision of what result they will have when they\u2019re done.<\/p>\n You won\u2019t learn how to write good requirements from reading a book on software requirements engineering or a book on technical writing. You need practice. Write requirements to the best of your ability, and then enlist some of your colleagues to review them. Constructive feedback from reviewers can help anyone become a better writer. In fact, it\u2019s essential. Requirements quality is in the eye of the reader of the requirements, not the author. No matter how fine the author thinks the requirements are, the ultimate arbiters are those who must base their own work on those requirements.<\/p>\n Also read\u00a0Elements of Requirements Style, Part 1<\/a><\/p>\n Also read\u00a0Elements of Requirements Style, Part 2<\/a><\/p>\n Also read\u00a0Elements of Requirements Style, Part 3<\/a><\/p>\n Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.\u00a0 Karl Wiegers is an independent consultant and not an employee of Jama. \u00a0He can be reached at\u00a0<\/i>http:\/\/www.processimpact.com<\/a><\/i>.\u00a0 Enjoy these free\u00a0<\/i>requirements management resources<\/a><\/i>.<\/i><\/p>\n","protected":false},"excerpt":{"rendered":" Ambiguity is one of the biggest problems I see with requirements specifications written (as they all are) in natural language. There is no end to ways that people can miscommunicate through the written word. The business analyst\u2019s goal is to try to make the meaning of each requirement as precise and clear as possible, aiming […]<\/p>\n","protected":false},"author":68,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"inline_featured_image":false,"footnotes":""},"categories":[50],"tags":[51,115,38],"industry":[],"class_list":["post-3436","post","type-post","status-publish","format-standard","hentry","category-requirements-management","tag-business-requirements","tag-elements","tag-karl-wiegers"],"acf":[],"yoast_head":"\n\n
Similar-Sounding Words<\/h2>\n
Adverbs<\/h2>\n
\n