Avoid Requirement Confusion By Using "The Active Voice"

©2015 Dwayne Wright

The software developers didn't fulfill one of your requirements and you clearly stated that something needs to be done under a particular set of circumstances. What could have possibly gone wrong?

EXAMPLE: When a returned product has been received, the customers history is updated within the system and the replacement product is scheduled for shipment.

On its own, this requirement maybe a little vague. Let's imagine that it is grouped within a number of requirements that define this is a product return process handled by a customer satisfaction / inventory management system. Extending our imagination, lets say that everyone is clear about what should be happening. Again, what could have possibly gone awry?

If we were to implement the root cause analysis technique of "The 5 Whys", how many why questions would we get before uncovering the root cause? How about if we take a swing at it right now?

WHY 1) Why didn't the customers history record get updated?
ANSWER 1) The system wasn't programed to automatically add this entry.

WHY 2) Why wasn't the system programmed to automatically update the customer history?
ANSWER 2) The requirement didn't say that the system did the updates, so the developer assumed this would be done by the data entry person.

WHY 3) Why didn't the requirement state that the update should be handled automatically by the system?
ANSWER 3) Stakeholder wasn't sure what the business rules would be to drive an automatic update.

WHY 4) Why didn't the requirement state that the update should be handled manually by a person?
ANSWER 4) Stakeholder wasn't sure which individual would perform the task and the associated business rules for the manual process.

WHY 5) Why didn't the analyst and stakeholders see this missing gap in business rules?
ANSWER 5) This requirement was written early in the process to meet a early requirement documentation milestone. Because it was written in a passive voice, it didn't specifically call out who did the task. 

SO WHAT IS THE RECOMMENDATION?
Requirements that are written in the active voice specifically call out the entity that is responsible for the action. Going forward, all requirements should be written in the active voice. If a situation arises like the one described above (and it will by the way), the analyst should choose one of the options and then put a TBD in place of the business rules. 

Yes, adding a TBD (to be determined) in the business rules is a short term delay in resolving the requirement. However, a TBD is much easier to catch than a requirement that is written in the passive voice.