SEG 3300 WRITING BETTER REQUIREMENTS

1
SEG 3300WRITING BETTER REQUIREMENTS

• Supplement to Chapter 4
• Source Ian Zimmerman, Daniel Amyot
• Telelogic, July 9, 2001

2
Standard for writing a requirement

• Each requirement must first form a complete
  sentence (not a bullet list of buzz words, list
  of acronyms, or sound bites on a slide).
• Each requirement contains a subject and predicate
  where the subject is a user type or the system
  under discussion, and the predicate is a
  condition, action, or intended result.
• Consistent use of the verb
• shall, will,or must to show mandatory
  nature
• should or may to show optionality
• Usually, shall and should are used.
• The whole requirement provides the specifics of a
  desired end goal or result.
• Contains a success criterion or other measurable
  indication of the quality.

3
Anatomy of a good user requirement
Defines a user type
To be verb
The internet user shall be able to access their
current account balance in less than 5 seconds.
Defines a positive end result
Performance criteria

• This requirement sentence identifies a specific
  user and end result that is wanted within a
  specified time.
• It also defines the success criteria in
  measurable terms - access ... account balance
  in less than 5 seconds.
• The challenge is to seek out the user type, end
  result, and success measure in every requirement
  you define.

4
Writing Pitfalls to Avoid

• Avoid Ambiguity
• Write as clearly and explicitly as possible
• Ambiguities can be caused by
• the word or to create a compound requirement
• poor definition (giving only examples or special
  cases)
• lax definition (use of etc, and so on)
• Dont make multiple requirements
• Keep each requirement as a single sentence.
• Requirements which contain conjunctions (words
  that join sentences together) are dangerous.
• Dangerous conjunctions include and, or,
  with, also.

5
Writing Pitfalls to Avoid

• Never build in let-out or escape clauses
• Requirements with let-outs or escapes are
  dangerous
• Ask for something definite, but later back down
  and allow for other options
• Problem arise in testing
• Dangerous let-outs include if, but, when,
  except, unless, although.
• Dont Ramble
• Long sentences with arcane language
• References to unreachable documents

6
Writing Pitfalls to Avoid

• Refrain from designing the system
• Requirements should specify the design envelope
  for the level required. If you supply too much
  detail you design the system (and increase the
  cost of systems).
• Danger signs include names of components,
  materials, software objects, fields records in
  the user or system requirements.
• Mixing different kinds of requirements
• Avoid mixing up requirements for users, system,
  and how the system should be designed, tested, or
  installed.
• Danger signs are very high level requirements
  mixed in with database design, software terms, or
  very technical terms.

7
Writing Pitfalls to Avoid

• Do not speculate
• There is no room for wish lists general terms
  about things that somebody probably wants.
• Danger signs include vagueness about which type
  of user is speaking, and generalisation words
  usually, generally, often, normally, typically .
• Do not use vague indefinable terms
• Many words used informally to indicate system
  quality are too vague to be verified.
• Vague terms include user-friendly, highly
  versatile, flexible, to the maximum extent,
  approximately, as much as possible, minimal
  impact.

8
Writing Pitfalls to Avoid

• Do not express suggestions or possibilities.
• Suggestions that are not explicitly stated as
  requirements are invariably ignored by
  developers.
• Possible options are indicated with terms such
  as may, might, should, ought, could, perhaps,
  probably.
• Avoid wishful thinking
• Wishful thinking means asking for the impossible.
  
• Wishful terms include 100 reliable. Safe.
  Handle all failures. Fully upgradeable. Run on
  all platforms.

9
Rate these Requirements
Are these good requirements? If not recommend an
improvement.

1. The Order Entry system provides for quick, user-
   friendly and efficient entry and processing of
   all orders.
2. Invoices, acknowledgments, and shipping notices
   shall be automatically faxed during the night, so
   customers can get them first thing in the
   morning.
3. Changing report layouts, invoices, labels, and
   form letters shall be accomplished.
4. The system shall be upgraded in one whack.

10
Rate these Requirements
Are these good requirements? If not recommend an
improvement.

1. The Easy Entry Navigator module converges the
   elements of order entry and communications, order
   processing, result processing, and reporting. The
   Order Entry module is fully integrated with the
   Organization Intranet System and results are
   stored in the groups electronic customer record.
2. Easy Entry shall be easy to use and require a
   minimum of training.
3. The system has a goal that as much of the IS data
   as possible be pulled directly from the TM
   estimate.

Remember the key questions -
WHY? or What is the purpose of this?