Writing Better Requirements

Based on slides by Gunter Mussbacher

with material from:
Ian Zimmerman (Telelogic, 2001),
Ivy Hooks (Compliance Automation, 1998)
Table of Contents
• Martha can’t write requirements because…

• Anatomy of a Good / Bad User Requirement

• Standard for Writing a Requirement

• Writing Pitfalls to Avoid

• A Few Simple Tests…

• The greatest challenge to any thinker is stating the problem in

a way that will allow a solution.1
[1] Bertrand Russell, 1872-1970
2
3
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Martha can’t write requirements because…

• She doesn’t know what to do!
• She was not taught at school
• She doesn’t know how to write
• She doesn’t understand the process
• She doesn’t have the necessary data
• She doesn’t know what she wants
• She doesn’t understand why!
• She doesn’t understand the impact / changes
• She thinks this is “just a document”
• She’d rather do something else!
• She’d rather design – she sees no reward
• She doesn’t have enough time
• She thinks the review process will catch the errors
Source: Compliance Automation, Inc., 1998
4
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Anatomy of a Good User Requirement

Defines the system under discussion Verb with correct identifier (shall or may)

The Online Banking System shall allow the Internet user

to access her current account balance in less than 5 seconds.

Defines a positive end result Quality criteria

• Identifies the system under discussion and a desired end

result that is wanted within a specified time that is
measurable

• The challenge is to seek out the system under discussion,

end result, and success measure in every requirement
5
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Example of a Bad User Requirement

Cannot write a requirement on the user No identifier for the verb

The Internet User quickly sees her current

account balance on the laptop screen.
X
Vague quality criteria What versus how

6
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Standard for Writing a Requirement

• Each requirement must first form a complete sentence
• Not a bullet list of buzzwords, list of acronyms, or sound bites on a
slide

• Each requirement contains a subject and predicate

• Subject: a user type (watch out!) or the system under discussion
• Predicate: a condition, action, or intended result
• Verb in predicate: “shall” / “will” / “must” to show mandatory nature;
“may” / “should” to show optionality

• The whole requirement provides the specifics of a desired

end goal or result
• Contains a success criterion or other measurable indication of
the quality
7
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Standard for Writing a Requirement

• Several standards define fairly precisely how to use key
words (verbs and adjectives) in their documents.

• Example: IETF RFC 2119: Key words for use in RFCs to

Indicate Requirement Levels

• MUST, REQUIRED or SHALL: mean that the definition is an absolute

requirement of the spec.
• MUST NOT or SHALL NOT: absolute prohibition
• SHOULD or RECOMMENDED: think twice about not doing it!
• SHOULD NOT or NOT RECOMMENDED: think twice about doing it!
• MAY or OPTIONAL: truly optional

8
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Standard for Writing a Requirement

• Look for the following characteristics in each requirement
• Feasible (not wishful thinking)
• Needed (provides the specifics of a desired end goal or result)
• Testable (contains a success criterion/other measurable indication of
quality)
• Clear, unambiguous, precise, one thought
• Prioritized
• ID

• Note: several characteristics are mandatory (feasible,

needed, testable) whereas others improve communication

9
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Writing Pitfalls to Avoid

• Never describe how the system is going to achieve
something (over-specification), always describe what the
system is supposed to do
• Refrain from designing the system prematurely
• Danger signs: using names of components, materials, software objects,
fields & records in the user or system requirements
• Designing the system too early may possibly increase system costs
• Do no mix different kinds of requirements (e.g., requirements for
users, system, and how the system should be designed, tested, or
installed)
• Do not mix different requirements levels (e.g., the system and
subsystems)
• Danger signs: high level requirements mixed in with database design,
software terms, or very technical terms
• Beware: may depend on the level of abstraction…
10
• Your what is my how!
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Writing Pitfalls to Avoid

• “What versus how” test
The system shall use Microsoft Outlook to send an
email to the customer with the purchase confirmation.
X
The system shall inform the customer
that the purchase is confirmed.

11
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Writing Pitfalls to Avoid

• Never build in let-out or escape clauses
• Requirements with let-outs or escapes are dangerous because of
problems that arise in testing
• Danger signs: if, but, when, except, unless, although
• These terms may however be useful when the description of a general
case with exceptions is much clearer and complete that an enumeration of
specific cases
• 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)
• The words etc., …and so on (imprecise definition)

12
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Writing Pitfalls to Avoid

• Do not use vague indefinable terms
• Many words used informally to indicate quality are too vague to be
verified
• Danger signs: user-friendly, highly versatile, flexible, to the maximum
extent, approximately, as much as possible, minimal impact

The EasyEntry System shall be easy to use and require

a minimum of training except for the professional mode.
X

13
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Writing Pitfalls to Avoid

• Do not make multiple requirements
• Keep each requirement as a single sentence
• Conjunctions (words that join sentences together) are danger signs:
and, or, with, also
• Do not ramble
• Long sentences with arcane language
• References to unreachable documents

The Easy Entry Navigator module shall consist of order

entry and communications, order processing, result
X
processing, and reporting. The Order Entry module shall be
integrated with the Organization Intranet System and
results are stored in the group’s electronic customer record.

14
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Writing Pitfalls to Avoid

• Do not speculate
• There is no room for “wish lists” – general terms about things that
somebody probably wants
• Danger signs: vague subject type and generalization words such as
usually, generally, often, normally, typically
• Do not express suggestions or possibilities
• Suggestions that are not explicitly stated as requirements are
invariably ignored by developers
• Danger signs: may, might, should, ought, could, perhaps, probably
• Avoid wishful thinking
• Wishful thinking means asking for the impossible (e.g., 100% reliable,
safe, handle all failures, fully upgradeable, run on all platforms)

The Easy Entry System may be fully adaptable to all

situations and often require no reconfiguration by the user.
X
15
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

A Few Simple Tests…(1)

• “What versus how” test discussed earlier
• Example: a requirement may specify an ordinary differential equation
that must be solved, but it should not mention that a fourth order
Runge-Kutta method should be employed

• “What is ruled out” test

• Does the requirement actually make a decision (if no alternatives are
ruled out, then no decision has really been made)
• Example: a requirement may be already covered by a more general
one

Source: Spencer Smith, McMaster U.

16
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

A Few Simple Tests…(2)

• “Negation” test
• If the negation of a requirement represents a position that someone
might argue for, then the original decision is likely to be meaningful
The software shall be reliable. X

Source: Spencer Smith, McMaster U.

17
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Towards Good Requirements Specifications (1)

• Consistent
Valid (or “correct”)
• Does not contradict
Expresses itself (satisfiable)
actual requirements
• Complete
• Uses all terms consistently
• Specifies
Note: inconsistency
all the things
canthe
besystem
hard tomust
detect,
doespecially
(including in
contingencies)
concurrency/timing
• aspects
...and alland
the condition logicnot do!
things it must
•• Formal modeling can help
Conceptual Completeness
• Beneficial
(e.g., responses to all classes of input)
• Structural
Has benefits
Completeness
that outweigh the costs of development
(e.g., no TBDs!!!)

Source: Adapted from Blum 1992, pp164-5 and the IEEE-STD-830-1993

18
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Towards Good Requirements Specifications (2)

• Verifiable
Necessary
• A
Doesn’t
process
contain
existsanything
to test satisfaction
that isn’t “required”
of each requirement
• Unambiguous
• “every requirement is specified behaviorally”
• Understandable (clear)
• Every statement can be read in exactly one way
• Clearly
E.g., bydefines
non-computer
confusing
specialists
terms
• (e.g., in a glossary)
Modifiable
• Uniquely identifiable
• Must be kept up to date!
• For traceability and version control

Source: Adapted from Blum 1992, pp164-5 and the IEEE-STD-830-1993

19
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Typical Mistakes
• Wishful
Noise = thinking
the presence
= textof
that
text
defines
that carries
a feature
no relevant
that cannot
information
possiblytobeany
feature of the problem
validated
• Jigsaw
Silence puzzles
= a feature
= e.g.,
thatdistributing
is not covered
requirements
by any text across a document and
• then cross-referencing
Over-specification = text that describes a feature of the solution, rather than
• Inconsistent
the problem terminology = inventing and then changing terminology
• Putting
Contradiction
the onus
= text
on the
thatdevelopment
defines a single
stafffeature
= i.e. making
in a number
the reader
of work
incompatible
hard to decipher
waysthe intent
• Writing
Ambiguity
for =the
text
hostile
that can
reader
be interpreted
(fewer of these
in >=2
exist
different
than friendly
ways ones)
• Forward reference = text that refers to a feature yet to be defined

Source: Steve Easterbrook, U. of Toronto

20
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Rate these Requirements

The Order Entry system provides for quick, user- X

friendly and efficient entry and processing of all orders.

Invoices, acknowledgments, and shipping notices shall X

be automatically faxed during the night, so customers
can get them first thing in the morning.

Changing report layouts, invoices, labels, and form

letters shall be accomplished.
X
The system shall be upgraded in one whack. X
The system has a goal that as much of the IS data as X
possible be pulled directly from the T&M estimate.

21
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

Key Questions and Characteristics

• Remember the key questions “Why?” or
“What is the purpose of this?”

• Feasible

• Needed

• Testable
22
Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools

A Few Syntactic Analysis Tools

• QuARS
• Quality Analyzer of Requirements Specification
http://www.sei.cmu.edu/publications/documents/05.reports/05tr014.html

• ARM
• Automated Requirement Measurement Tool
http://www.stcsig.org/quality/newsletters/NL0603/NL0603_Doc_Value-pf.html

• TIGER Pro
• Tool to Ingest and Elucidate Requirements
• http://www.therightrequirement.com/TigerPro/TigerPro.html

23