Writing Great Requirements: Don’t Be Passive
One of the most important factors in any technical project’s success is clearly and accurately describing the overall business process. If you don’t really understand who is impacted by a change and what they will specifically do, then you won’t deliver on your goals. Recently, I’ve reviewed several plans for technical changes that have fallen into the a trap. They’ve used “passive voice” to mask uncertainty in the process.
For those of you who haven’t taken grammar school writing class lately, passive voice is when you move the object of a sentence before the action. For example, “The email will be sent after the report is reviewed.” The object in the sentence “the email” is before the action “sent”. In fact, this sentence is a double whammy since we’ve put “report” before “reviewed.”
Why is this so ineffective? Imagine emailing this sentence to 6 people. If you asked those people, “who is sending the report and who is reviewing it,” some might think they’d all have different answers. I disagree. I think they’d all have the exact same answer… “not me!”
Passive voice is a crutch we use for two reasons. Either we didn’t take the time to really think through the exact sequence and owners of a process, or we’re avoiding calling out the fact that we’re pushing more responsibility to someone else.
Unfortunately, when you avoid these problems at the beginning of a project, you spend 10x more time fixing them later. You’ll spend your time much more effectively if you stop and clarify the intent up front.
Fixing the problem is easy, and also takes us right back to grammar school. If you are writing a requirement, explicitly answer who, what, when, where, why, and how. If someone sends you a requirement that doesn’t answer these questions, you must stop and ask until the requestor has answered the questions. This can be difficult, especially if the requestor is your boss (or worse, a committee.) Remember that you are doing everyone a favor. The upfront inconvenience will help avoid delivering the wrong product at the end.
How can we improve our original sentence?
“At 7am EST each day, the accounting reporting system will email an audit report to George’s address. George will review the report and validate values over $10,000. He’ll call Jean when there are problems. This process should help reduce chargebacks by 50%.”
That’s a heck of a lot longer, but it fleshes out a lot of potential issues that the original requirement ducked. Does George have time to do this every day? Can Jean help him? Is this the best way to address the chargebacks? Is $10,000 the right cutoff value?
Eventually all of these questions need to be addressed. Isn’t it better to do it up front?
