The Mystery of Requirements

Many times in writing or reviewing requirements we tend to be a little “sloppy” in our writing. We need to remember that are not writing a mystery. What are some qualities of a good mystery novel?

• There is an underlying theme to the mystery.
• There are a lot of great characters involved.
• There is a clear setting where the story takes place.
• The final few chapters hold the climax of the story.

In other words, the author gives us clues all along, but it isn’t until the last few pages that we suddenly understand what the author has been trying to tell us all along.

Let’s take this approach with requirements. What makes requirements a mystery?

• There is no underlying theme. In other words, there is no clear reason, business or otherwise, why we are even doing this project.
• We get some of the characters involved, but we tend to miss some too. Making sure we have included everyone who is impacted by the project in any way is an important component.
• We’re not sure where the story takes place. To make a comparison, we don’t know where the product will be deployed or who will be using it. We need to know the setting.
• We are not persistent in understanding all of the clues the users give to us. There are lots of clues if we just pay attention. Users and stakeholders give us clues in many ways. Sometimes the clue may be in the way they respond to our questions in a nonverbal manner (i.e. rolling their eyes, crossing their arms, etc.). They may state assumptions about what they are thinking, yet another kind of clue for us. Sometimes a clue may lie in unspoken requirements that we have to try and get the users to verbalize for us. And sometimes the clues are in the form of a solution. When the users give us a solution they are really giving us a clue that they have a problem they are trying to solve. We must strive to understand what that problem really is.

The end of a mystery is exciting and gets our blood moving. We’re not sure until the last few pages that we really understood everything. If we manage projects in the same way we are in trouble. Software development should not be a mystery to us. We can’t wait until deployment to make sure that we solved the problem correctly. We want our requirements to be as clear and correct as possible from the beginning.

So here are some simple guidelines for writing requirements in a simple and concise statement, and removing some of that mystery.

• Every requirement should be a complete sentence. (i.e. a subject, verb and predicate with a period at the end) Remember our old English classes when we actually diagrammed sentences?
• Every requirement should describe clear success criteria. (The user shall be able to view the Audit Log Report.)
• Every requirement should state a single action and objective. Watch out for excessive use of “and” and “or”. For example:(If is the last Friday of the month and the payment is due on the 31^st, and if the 31^st is the last Friday of the month, then submitting the payment on that day after 6pm eastern time will result in a late payment.) I challenge to understand that one!
• A requirement should not have an escape clause. (The System shall determine the number of login attempts except when the user has clearly entered an incorrect username.)

Let’s make sure our requirements are not a mystery!

By: Marcia Stinson