This is a brief article, so I’ll skip the debate over about whether detailed software requirements are (a) the cornerstone of all better-than-awful software or (b) a stumbling block for gazelle-like coders. Either way, in my world (medical devices), there is no debate: FDA insists that your requirements be detailed enough to ensure that the software works the way the user expects it to. So if you have the good fortune to be tasked with writing software requirements, here are some helpful rules.
1. You have Four Customers.
These are the manager (product manager, boss, client, etc.); the developer; the tester; and the user (for whom many tech writers claim to “advocate”). Of course, your customers might have conflicting interests, like a manager’s demand for an interface that’s flashy! and innovative! and full of exclamation marks! … while the user just wants the darn thing to work. But good communication can reduce conflict, and you’re the only professional communicator in the room. If nothing else, well-written requirements will at least clarify those conflicts in advance.
2. Include everything that matters, and nothing that doesn’t.
Many features are determined by developers who were given only general guidelines. After they’re done coding, someone comes along and complains that salmon is not the right color for the Cancel button. Well, why didn’t you say so? Of course, for a requirement detail to “matter,” at least one of your Four Customers has to care about it. If no one minds, it doesn’t matter; leave it out of the requirement and let the developer have some fun.
3. Write your requirements in stimulus-response format.
For example: “When a finger-swipe moves in a clockwise motion with a speed ≥ 1 cm/second [stimulus], the cursor shall rotate ninety degrees clockwise [response].” The stimulus may be a user action, the passage of time, a signal from other software, etc. The manager often focuses on the response, but the stimulus is critical for the tester: If your requirement’s stimulus conditions lack detail, the tester can’t create a reproducible test.
4. Don’t combine requirements.
Most software has multiple options for input (stimulus), and it’s easy to end up with a requirement like, “When the user clicks the Save button or presses CTRL+S, MS Word shall crash.” But these are really two distinct requirements: “When the user clicks the Save button, MS Word shall crash,” and “When the user presses CTRL+S, MS Word shall crash.” Believe me, your tester wants you to separate them.
5. Speak with conviction.
When requirements are drafted with team input, words like “should,” “might,” and “possibly” tend to creep unbidden into the document. But requirements aren’t like Barbossa’s pirate code; they are rules, not guidelines. The software shall do this; it shall do that. (I’ll let you choose between “will” and “shall,” but you know which side I’m on.)
So there you have it. You don’t need to know code to write proper software requirements, but you do need to listen to your Four Customers and draw them a clear picture of the work to be done. Yes, it’s challenging, but it’s a lot easier (and cheaper!) than fixing the thing after it’s already been built.
Special thanks to David Vogel of Intertech, whose AAMI workshop on medical software validation introduced me to the joy of requirements writing.
