This is the third entry in a series on what constitutes good requirements, regardless of how they are written, stated, shown, or otherwise intended.  In this entry, we cover how language affects the ambiguity of requirements. When requirements are unambiguous it means that they have one and only one interpretation by everyone involved.

How would you respond to this personal ad?

SINGLE FEMALE seeks male companionship, ethnicity unimportant.  I’m a very good looking girl who loves to play. I love long walks in the woods, riding in your pickup truck, hunting, camping, fishing trips, and cozy winter nights lying by the fire. Candlelight dinners will have me eating out of your hand. I’ll be at the front door when you get home from work wearing only what nature gave me. Call and ask for Daisy.

The Atlanta Humane Society received over 15,000 calls asking for Daisy – a Labrador Retriever!

There is nothing like that terrible moment when two people come to the realization that they have two very different expectations about something like a key feature of your software. Of course, Murphy’s Law states that this realization will occur the day before the product demo to the senior management team.  In the previous post in this series, we discussed ways to ensure that the requirements are correct and complete, which goes a long way in preventing these painful situations. But it is not enough.

Ambiguous requirements are actually a great way to get the project ideas off the ground and get the project team in the same ballpark. You can quickly get a sense of the direction the product needs to go, what features are important, and some the technical challenges you will have.  Somewhere between a hallway conversation and a white board sketch that was subsequently erased, we get can pretty close. But close only counts in horseshoes and hand grenades, and eventually we need to ensure that everyone involved has the same understanding.

As I’ve said before, this is not an endorsement of one methodology or another. We can try to write all of the requirements perfectly up front, and we can patiently iterate on the product to determine the product readiness as we go.  Both are strategies that have evolved to ensure that the product and requirements are lined up. And of course our friend at the IEEE have also pondered this problem in IEEE 830-1998. What follows is a collection of tips and red flags to avoid ambiguous language.

1. Replace every pronoun, particularly “it” or “its.” Each should have an explicit and unmistakable reference.
2. Avoid passive voice, such as “the counter is set.” (By whom or what?)
3. Vague words and phrases such as: almost, applicable, but not limited to, generally, ideally , including, nearly, normally, optionally , sometimes, timely, to the greatest extent, when necessary, where practical.
4. Imprecise verbs such as: be able to, be capable, handled, maximize, processed, provide for, supported.
5. Implied certainty is a flag for suspicious ambiguity. Avoid words such as: all, always, every, never, none.
6. Comparatives such as: earliest, highest, improved, latest, words ending in “-er” or “-est” should be suspect.
7. Words and phrases that are not or cannot be quantified such as: , accomplish, achievable, adequate, as a minimum, better, correct (or correctly) , efficient, fast, faster, flexible, higher, infrequent, less, minimum acceptable, minimum required, modular, normally, often, possible (or possibly) , several, slower, steady-state, sufficient, to be associated with, to be compatible, to the extent required, to the extent , specified, typically.
8. Words and phrases whose meaning can be disputed between developer and customer such as: achievable, adjacent, average, coincident, degraded, easy-to-use, effective, finish, flexible, instantaneous, intuitive, minimum, nominal, normal, reasonable,  appropriate, seamless, simple, simultaneous, state-of-the-art, synchronous, transparent, user-friendly.

The next post in this series will be delivered soon, ideally with a higher level of satisfaction, acceptable meaning, and improved user-friendliness. It will be published in the future…

This is the second entry in a series on what constitutes good requirements, regardless of how they are written, stated, shown, or otherwise intended.  In this entry, we cover two characteristics that go hand in hand and are generally the responsibility of the customer and user: correct and complete.

You probably haven’t tried my grandmother’s meatloaf, but trust me, it is fantastic. A few weeks ago we decided to make this legendary meal on our own. My wife sent me to the grocery store with a shopping list: carrots, onions, eggs, ground beef.

I picked up everything on the list, but when I returned home we discovered that we were missing one ingredient: bread. I verified that it wasn’t, in fact, written on the shopping list and returned to the store. The list did not meet a key characteristic; it was not complete.

Now that we had all of the ingredients, we set to cooking and then eating. But something just wasn’t right with the meatloaf.  We called my grandmother and it turns out that she uses ground veal, not ground beef. The list did not meet another key characteristic; it was not correct.

Think about these characteristics as they relate to software development.  In a waterfall approach, you have to be pretty darned good to get all of the requirements exactly right.  In an Agile approach, you have to be pretty darned patient to let the iterative process take you down the right path. But no matter what approach you use, you need to be mindful of correctness and completeness. IEEE (in its own formal and, um, charming way) addresses these concerns in STD 830-1998. I’ll leave it to you to read up on their verbiage in section 4.3.

Complete requirements imply that we know the truth, the whole truth, and nothing but the truth. By the time we are done with the product, it includes everything the users need to complete their tasks and accomplish their goals.  There are no TBDs – anywhere. Missing requirements are hard to find because they aren’t there. The best way to determine if the requirements are complete is through ongoing exploration of, mining for, and testing of the requirements and system as it progresses.

Questions to ask: What is missing? Have we talked to everyone? Do the requirements satisfy every business scenario and outcome that is in the scope? Are the requirements and components traceable up to some need or business purpose? If my users require a login ID and password, have we defined how they will reset and recover their passwords (you might be surprised how often this gets overlooked)? Are all 11 secret herbs and spices accounted for?

Correct requirements imply that the requirements we actually know about are the right ones, and accurately describe how the product functions so that users can complete their tasks and accomplish their goals. One of the best techniques for ensuring correct requirements is to ensure that the documentation and code is reviewed, validated, and tested on an ongoing basis by the subject matter experts themselves.  Writing test cases in conjunction with requirements takes this a step further.

Questions to ask: Is this right? Is this calculation correct when I enter high, low, and out of range values? Does this field hold up in all situations? Is that Eastern Daylight Time or Eastern Standard Time?  Did you say “patients” or “patience?”

Again, whether you are writing a comprehensive tome of requirements or you are having a conversation with your users about a prototype you just built, make sure you are getting on the same page with what is complete and correct. And if you are looking for a recipe for Sunday dinner, don’t ask me. Call my grandmother.