It’s always the requirements fault! Whenever anything goes wrong with a software development project the requirements tend to be the scapegoat. It is a fact of life as a BA that at some point the requirements you write will be wrongly blamed for a mistake in the product. In reality, any oversight in the product is the responsibility of the entire development team. So what can the BA do to ensure they are not the convenient scapegoat for an issue with the product? The answer is to consistently deliver clear requirements that leave no room for multiple interpretations or ambiguity. Fortunately there is a simple recipe which may be used to ensure you are consistently writing clear and unambiguous requirements.
Step 1: Use Subject-Verb-Object Format
The key to clarity in the English language is the relationship between the Subject, Verb and Object (SVO Format). If a common sentence clearly defines WHO the Subject is, WHAT they will be doing and WHO they are doing it to then the reader should have no problem understanding it. To turn a common sentence into a requirement we must introduce a strong auxiliary verb such as “must” or “will”. For example:
Try reading the example sentence using only the Subject, Auxiliary verb, Verb and Object. “Users must create user account” makes sense even when the supporting words are removed. Always use simple verbs that are well understood. For example, when writing requirements related to the management of data consider that there are only four operations which may be completed:
1). Create
2). Read
3). Update
4). Delete.
These operations are commonly referred to as CRUD.
However, when writing requirements related to CRUD operations consider using the following simple verbs:
- Enter
- Display
- Edit
- Delete
For example, consider that a customer needs to enter their email address into the system. The requirements related to accomplishing this goal could be:
- “A customer must be able to enter their email address into the system.” (CREATE)
- “The system must display a customer’s email address when viewing their account profile.” (READ)
- “A customer must be able to edit their email address within the system.” (UPDATE)
- “A customer must be able to delete their email address from the system.” (DELETE)
The use of these simple verbs makes it very clear what the system must accomplish.
Step 2: Use Strong Auxiliary Verbs
Ambiguity and confusion can be prevented with the consistent use of strong auxiliary verbs such as “must”, “will”, “must not” or “will not”. Weak auxiliary verbs such as “may”, “should”, “could” and “can” may be misinterpreted and cause confusion. Once you choose a strong auxiliary verb make sure you use it consistently in all of your requirements. Do not write some requirements using the word “must” and others using the word “will”. Consistency leads to clarity. You may have noticed I did not mention the word “Shall”. In my opinion it is a traditional practice to use the word “shall” within a requirement. However, I am of the opinion that “shall” is actually a weak auxiliary verb and prefer the word “must”.
Step 3: Use Active Voice and Present tense
Active voice is much easier to read and significantly reduces ambiguity. The reader doesn’t have to figure out who is doing what. For example:
Passive voice: “A user account must be created for the customer.”
Passive requirements have the Subject at the end of the sentence. This style often leads to misunderstanding since someone could reasonably question who is creating the account for the customer. In Active Voice the subject performs the action which is expressed by the verb. To change a passive sentence to active voice you need to change the verb. For example:
Passive voice: Resetting a password must be a function available to a customer.
Active voice: A customer must have the ability to reset their password.
Step 4: Keep it Simple
Avoid writing long paragraphs. When writing requirements you are not writing a novel. Grammatical creativity and showing off your vocabulary skills will not be received well by the development team. Back away from the thesaurus and keep it simple!
Step 5: Avoid Ambiguity
Ambiguity will destroy the understanding of your requirements. It is the BA’s kryptonite and must be avoided at all costs! We’ve all seen ambiguous signs in our daily lives that we may not even notice. Some of my favorite ambiguous signs are:
“Please wait for hostess to be seated.”
Am I waiting for her to be seated or am I waiting for her to seat me?
“Slow children at play.”
Are the children so slow they can’t avoid the cars? Or should I drive slowly because there are children around?
“Entire store 25% off!”
May I buy the actual store for 25% off or are all the contents 25% off?
“Nothing works better or faster than our product!”
Hmmmm….should I buy your product or should I just go with nothing?
I’ve seen many ambiguous requirements in my career but my all-time favorites were found at an organization that hired me as the first Business Analyst they ever had. Prior to my arrival anyone in the development group could write requirements. Here are a couple of classics that demonstrate ambiguity:
“The system may generate some alerts according to study requirements, if applicable.”
“The alert will send over and over again for any missed visit.”
According to these incredibly ambiguous requirements it appears the system will be sending some type of an alert over and over again for the rest of eternity! I feel sorry for the person who has to test this requirement!
We can deal with ambiguous signs in our daily lives but ambiguous requirements are guaranteed to bring chaos to a software development project.
Step 6: Requirement Clarity Top Ten List
For each requirement you write ask the following questions:
- Is the requirement written in S-V-O format?
- Is the requirement written in active voice using a strong auxiliary verb?
- Does the requirement focus on the business need rather than a technical solution?
- Is the requirement easy to understand by all audiences?
- Is the requirement simple, short, and unambiguous?
- Will an example improve the understanding of the requirement?
- Will a visual figure or wireframe improve the understanding of the requirement?
- Can the requirement be tested?
- Does the requirement contradict any other requirement?
- Does the requirement describe how it must be implemented (Ex: display in alphabetic order, ascending/descending order, required/optional field, alphanumeric, numeric, etc.)
Asking these questions while reviewing the requirements you have written will help ensure that the requirement is clear, concise and unambiguous. Consistently following this recipe will improve your requirements and help you avoid becoming the convenient scapegoat for software failures.
Author: David Shaffer, Business Analysis, Reed Tech
Dave is the Manager of Business Analysis at Reed Tech in Horsham, Pa. where he is focused on mentoring Business Analysts and constantly improving the maturity level of Business Analysis within the software development group. He has established Business Analysis Centers of Excellence within the pharmaceutical, government and manufacturing industries since 2002 and may be reached via his LinkedIn profile https://www.linkedin.com/pub/dave-shaffer/0/894/681
Email: [email protected]