Writing Excellent Requirements

store. I wanted to ask you about the song preview feature. That’s not working the way I had in mind .”

Let me find the requirements you sent for that. Here they are. The user story said, ‘As a Customer, I want to

Gautam replied, “ listen to previews of the available songs so I can decide which ones to buy.’ My notes say that when we discussed this, you said each song sample should be 30 seconds long and that it should use our built- in MP3 player so the customer didn’t have to wait for another player to launch. Isn’t that working correctly? ”

Well, yes, that all works fine, ” said Ruth, “

but there are a couple of problems. I can click on the play icon to start the sample,

“ but I don’t have any way to pause it or stop it. I’m forced to listen to the entire 30

-second sample. Also, all the samples start

at the beginning of the song. Some songs have long introductions so you really can’t hear what they’re like from just the beginning. The sample should start somewhere in the middle of those songs so people could hear what they’re really like. And the sample starts playing at full volume and then stops abruptly. If the customer’s speakers are up pretty loud this could be startling. I think it would be better if we fade in and fade out on each sample. ” Gautam was a little frustrated. “

I wish you had told me all of this when we spoke earlier. You didn’t give me much to go on so I

just had to make my best guess. I can do all that, but it’s going to take a few more days. ”

• You can write functional requirements from the perspective of either something the system does or something the user can do
• Effective communication is the overarching goal, so it’s fine to intermingle these styles, using whichever is clearer

1. State requirements in a consistent fashion, such as “ The system shall ” or “ The user shall ,” followed by an action verb, followed by the observable result
2. Specify the trigger action or condition that causes the system to perform the specified behavior

The system shall let (allow, permit, or enable) the [a particular user class or name] to [do something] The [user class or actor name] shall be able to [do something] [to some object] [qualifying conditions, response time, or quality statement]

reduces misinterpretation

User class in place “user” –

E.g., The Chemist shall be able to reorder any chemical he has ordered in the past by retrieving and editing the order details

Helps those who are skimming through a document

• Adjust your writing style to put the punch line statement of need or — functionality first, followed by supporting details (rationale, origin, — priority, and other requirement attributes)
• Use tables, structures lists, diagrams, and other visual elements to help break the unvarying tone of functional requirements and provide richer communication to those who learn best in different ways

Clarity and conciseness

• Use complete sentences, proper grammer, spelling and punctuation
• Keep sentences and paragraphs short and direct – avoid jargon
• Define specialized items in glossary
• Write concisely needs to provide the user with the capability to ” can be
  • “ shall ” condensed to “
• But remember, clarity is more important than conciseness

shall

T

he keyword “

”

that’s not how people talk ”

• Objectors say “
• You might prefer to say must needs to “ ,” “ ,” or something similar, but be consistent

Active voice

• Write in the active voice to make it clear what entity is taking the action described Recipient Passive Upon product upgrade shipment, the serial number will be updated on the
• ” Performer? contract line ” Will the system do that automatically, or is the user expected to update the serial number?
• ” When Fulfillment confirms that they shipped a product upgrade, the system shall update the customer’s contract with the new product serial number ”

Individual requirements

• Avoid writing long narrative paragraphs that contain multiple requirements
• Clearly distinguish individual requirements from background or contextual information and or additionally ,” or “ ” in a requirement suggest that also
• Words such as “ ,” “ ,” “ several requirements might have been combined – you don’t necessarily have to and” , but make sure the conjunction is joining two parts of a single abandon “ requirement

Individual requirements

and/or

• Avoid using “ ” in a requirement; it leaves the interpretation up to the reader The system must permit search by order number, invoice number, and/or
  • “ customer purchase order number This requirement would permit the user ” – to enter one, two, or three numbers at once when performing a single search. That might not be what’s intended.

Appropriate detail

How detailed should the

• There’s no single correct answer to the commonly asked question, “ requirements be? ”
• Provide enough specifics to minimize the risk of misunderstanding, based on the development team’s knowledge and experience
• The fewer the opportunities for discussion about requirements issues, the more specific you need to be
• If a developer can think of several possible ways to satisfy a requirement and all are acceptable, the specificity and detail are about right

Consistent granularity

• Helpful guideline: write individually testable requirements
• If you can think of a small number of test cases to verify that a requirement was correctly implemented, it’s probably at an appropriate granularity
• If you envision numerous and diverse tests, perhaps several requirements are combined and ought to be separated

• Some alternatives to the natural language requirements are lists, tables, visual analysis models, charts, mathematical formulas, photographs, sound clips, and video clips
• These won’t suffice as substitutes for written requirements in many cases, but they serve as excellent supplemental information to enhance the reader’s understanding.

• Example: The Text Editor shall be able to parse <format> documents that define <jurisdiction> laws.
  • 3 possible values for <format> and 4 possible values for <jurisdiction> , for a total of 12 similar requirements
  • The SRS did indeed contain 12 such requirements, but one of the combinations was missing and another was duplicated.
  • Prevent such errors by representing them in a table, which is more compact and less boring than a requirements list.

Boundary values

through inclusive

exclusive

• Use “ ,” “ ,” and “ ” to denote whether the endpoints of the numerical range lie inside or outside the range Vacation requests of 5 or fewer days do not require approval. Vacation “ requests of longer than 5 days through 10 days require supervisor approval. Vacation requests of longer than 10 days require management approval. ”

Negative requirements – requirements that say what the system will not do rather than what it will do

-do-this requirement?

• How do you implement a don’t
• Double and triple negatives are particularly tricky to decipher! Prevent the user from activating the contract if the contract is not in balance. ”
  • “ The system shall allow the user to activate the contract only if the contract is in
  • “ balance.”

Negative requirements

• If you need to indicate that a certain functionality is out of scope, include the restriction in the Limitations and Exclusions section of the vision and scope document instead of listing it as a negative requirement

Example 1 The Background Task Manager shall provide status messages at regular intervals not less than every 60 seconds.

Example 1 The Background Task Manager shall provide status messages at regular intervals not less than every 60 seconds.

• What are the status messages?
• Under what conditions and in what fashion are they provided to the user?
• If displayed on the screen, how long do they remain visible?
• Is it okay if they just flash up for half a second?
• The timing interval is not clear, and the word “every” just muddles the issue

Example 1 The Background Task Manager shall provide status messages at regular intervals not less than every 60 seconds.

• Is the interval between status messages supposed to be at least 60 seconds, so providing a new message once per year is okay?
• If the intent is to have at most 60 seconds elapse between messages, would one millisecond be too short an interval? Because of these problems, this requirement is not verifiable

• Rewriting a flawed requirement often makes it longer because information was missing
• Splitting this into multiple child requirements makes sense because each will demand separate tests, and also each one will be individually traceable
• If there are other status messages that the BTM might display, list them in a table of conditions and corresponding messages. If they’re documented elsewhere in the document, reference them instead of replicating them.

Example 2 Corporate project charge numbers should be validated online against the master corporate charge number list, if possible.

Example 2 Corporate project charge numbers should be validated online against the master corporate charge number list, if possible.

• The phrase “if possible” is ambiguous ? (a question for the developer)
  • “ if it’s technically feasible”
  • “if the master charge number list can be accessed at run time”?
• If you aren’t sure whether a requested capability can be delivered, use TBD to indicate that the issue is unresolved. After investigation, either the TBD goes away or the requirement goes away.

Example 2 Corporate project charge numbers should be validated online against the master corporate charge number list, if possible.

• Doesn’t specify what to do when the validation either passes or fails should
• The word “ ” is imprecise

One way to rewrite it:

At the time the requester enters a charge number, the system shall display

“ an error message if the charge number is not in the master corporate charge number list. “

• A related requirement would address the exception condition of the master corporate charge number list not being available at the time the validation was attempted.

Example 3 The device tester shall allow the user to easily connect additional components, including a pulse generator, a voltmeter, a capacitance meter, and custom probe cards.

(This requirement is for a product containing embedded software that’s used to test several kinds of measurement devices)

Example 3 The device tester shall allow the user to easily connect additional components, including a pulse generator, a voltmeter, a capacitance meter, and custom probe cards.

• The word “easily” implies a usability requirement, but it is neither measurable nor verifiable
• “Including” doesn’t make it clear whether this is the complete list of external devices that must be connected to the tester or if there’s more

TRAP

Watch out for analysis paralysis. All of the sample “after ” requirements

can be improved further, but you can’t spend forever trying to perfect the requirements. Remember, your goal is to write requirements that

are good enough to let your team proceed with design and

construction at an acceptable level of risk.