It’s the Requirements fault! A Recipe for Requirement Clarity

Featured
21563 Views
8 Comments
33 Likes

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:

  1. Is the requirement written in S-V-O format?
  2. Is the requirement written in active voice using a strong auxiliary verb?
  3. Does the requirement focus on the business need rather than a technical solution?
  4. Is the requirement easy to understand by all audiences?
  5. Is the requirement simple, short, and unambiguous?
  6. Will an example improve the understanding of the requirement?
  7. Will a visual figure or wireframe improve the understanding of the requirement?
  8. Can the requirement be tested?
  9. Does the requirement contradict any other requirement?
  10. 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]

Like this article:
  33 members liked this article
Featured
21563 Views
8 Comments
33 Likes

COMMENTS

Anupama posted on Wednesday, December 16, 2015 1:36 AM
An excellent article on how to write requirements. Everything is explained in detail. Thanks Dave for sharing knowledge powerhouse!
Abhatt
DMCGUIRK posted on Thursday, December 17, 2015 3:06 AM
I really enjoyed this article. It would be really interesting to hear your thoughts on replacing the 'Shall' with other MoSCoW priorities instead i.e.Must, Should etc?
I have toyed with this idea a number of times but backed out at the last minute because at that point you don't know for definite the priority. But then would be useful to run through via a workshop to help to confirm.
Btw: for your examples: how would you then write your acceptance criterias?
DMCGUIRK
dshaffer posted on Thursday, December 17, 2015 8:05 AM
Thanks for the positive feedback DMCGUIRK! I've never been a fan of Moscow prioritization. IMO it is a textbook idea that fails in practice. When you have a large development team it's impossible to ensure everyone has the exact same understanding of what "Must", "Should" & "May" mean. It causes confusion. I simplify things. Every requirement is a "Must". I work with a product owner who determines what requirements are in scope or out of scope. If it is in scope then it is a "Must". Don't confuse acceptance criteria for requirements. IMO they are the exact same thing. In my example the User Story would be "Create Account". The 4 example requirements would be part of the acceptance criteria for that story. I hope this helps!
dhs101896
DMCGUIRK posted on Thursday, December 17, 2015 2:17 PM
Thanks David. I really do not disagree but I once debated the use of Must with a lecturer from the BCS quite recently during their Systems Design course. He argued that Must implies for definite and not all requirements carry the same weight in terms of value. Hence the BCS recommend 'Shall' instead. However, this can be debated forever and ever and truth is that both are suitable. The real overriding excellent headline point you made is that every one involved in the Lifecycle should share the responsibility.
I think next time I will use Must and see how it works for me since I have felt that it is more relevant too but kind of bottled it by using 'Find and Replace'. I completely agree with your insight and look forward to reading your future articles.
DMCGUIRK
DMCGUIRK posted on Thursday, December 17, 2015 2:21 PM
Find and Replace in MS word i.e to replace Must with Shall (then back again, then back again, then bang my head started to hurt - lol). Analysis can cause paralysis.
DMCGUIRK
Adriana Beal posted on Saturday, December 19, 2015 11:10 AM
David, thank you for sharing these great tips with the business analysis community. I wonder if you would agree, though, that your sample requirements could also use some improvement. For example:

“A customer must be able to enter their email address into the system.” (CREATE)

When I write requirements, one of questions I like to ask myself is, "would a tester know how to properly test this requirement without more context?". I'd say the answer here is no.

Imagine that the system in question already has a screen with a text field in which site visitors can enter any text, and the only thing it does it to show the entered text with an animated effect on the same page. This page satisfies the requirement as written (a customer is able to enter his/her email address into the system), but clearly that is not the intention of the requirement.

A tip I'd add to your list is to start from the end goal. Why would the customer would want or need to enter their email address into the system? What would trigger this action on the customer side? In my experience, answers to these kinds of question help better formulate a requirement that is complete, unambiguous, and testable.
adrianab
dshaffer posted on Monday, December 21, 2015 9:47 AM
Thanks for the feedback adrianab! My examples are fairly simplistic in order to illustrate the concepts associated with writing clear requirements. You are correct that my example may not be perfectly clear depending on the real world system it is associated with. You always need to consider the end goal of the customers when writing requirements. To do this I like to create an Actor - Goal list which helps identify who is using the system and for what reason. Every Actor - Goal combination is related to a specific User Story or Use case which has detailed requirements. I hope this helps provide further clarification for you!
dhs101896
RolandR posted on Tuesday, January 5, 2016 6:28 PM
I've always been wondering about the benefit of using auxiliary verbs phrases to formulate requirements. I personally don't see any added value, to me they are just unnecessary clutter. But they are so entrenched that many people apparently cannot live without them, among others the quality managers I'm working with.
To me a requirement "A user can enter an email address as part of his profile" is much more direct than "A user must be able to enter an email address as part of his profile" (the "must be able to" actually is somewhat ambiguous, too). In addition from my point of view the direct formulation can also immediately serve as a good starting point for test specifications.
rrenetseder
Only registered users may post comments.

 



Upcoming Live Webinars

 




Copyright 2006-2024 by Modern Analyst Media LLC