SEG3101
Writing Good Requirements and
Specifications
Daniel Amyot, University of Ottawa
Based on slides by Gunter Mussbacher
with material from:
Ian Zimmerman (Telelogic/IBM), Ivy Hooks (Compliance Automation)
ISO/IEC/IEEE 29148:2018
Table of Contents
• Writing Good Requirements
• Anatomy of a Good / Bad Requirement
• Standard for Writing a Requirement
• Writing Pitfalls to Avoid
• A Few Simple Tests
• Writing Good Specifications
• Requirements Specifications
• ISO/IEC/IEEE 29148:2018 Standard
2
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
The greatest challenge to any thinker is stating the problem in
a way that will allow a solution.
Bertrand Russell, 1872-1970
3
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Good & Bad
Standard
Pitfalls to Avoid
A Few Simple Tests
Summary & Tools
Anatomy of a Good 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 criterion
• The challenge is to seek out the system (or part thereof)
under discussion, the end result, and (if any) the success
measure in every requirement.
4
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Good & Bad
Standard
Pitfalls to Avoid
A Few Simple Tests
Summary & Tools
Example of a Bad Requirement
Cannot write a requirement on the user!
No modal identifier for the verb
The Internet User quickly sees her current
account balance on the laptop screen.
Vague quality criterion
X
What versus how
5
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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
• Several standards define 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
6
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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
• Needed (provides the specifics of a desired end goal or result)
• Feasible (not wishful thinking, take resources into account)
• Testable/Verifiable (contains a success criterion/other measurable
indication of quality)
• Unambiguous, precise, concise, correct, singular (one thought)
• Identifiable along all its life
• Note: several characteristics are mandatory (feasible,
needed, testable) whereas others aim to improve
communication
7
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Good & Bad
Standard
Pitfalls to Avoid
A Few Simple Tests
Summary & Tools
Writing Pitfalls to Avoid
• Never describe prematurely 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: all the above may depend on the level of abstraction…
• Your what at your level might be the how at my level!
8
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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.
9
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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 words or to create a compound requirement
• Poor definition (giving only examples or special cases)
• The words etc., …and so on (imprecise definition) J
10
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Good & Bad
Standard
Pitfalls to Avoid
A Few Simple Tests
Summary & Tools
Example of Ambiguities with “Or”
• The mobile app shall be available for Android or iOS.
• Is this or inclusive? Would it be incorrect to have this app available on
both platforms?
• The software shall be available for Windows or Linux and
MacOS.
• Where are the parentheses?!!!
• What are the subsets of {Windows, Linux, MacOS} that would satisfy
this requirement?
11
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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
X
The EasyEntry System shall be easy to use and require
a minimum of training except for the professional mode.
12
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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
X
The Easy Entry Navigator module shall consist of order
entry and communications, order processing, result
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.
13
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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)
X
The Easy Entry System may be fully adaptable to all
situations and often require no reconfiguration by the user.
14
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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)
The system shall produce report X3 once every day.
The system shall produce report X3 every Monday.
X
Source: Spencer Smith, McMaster U.
15
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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
• Failing that test may indicate the presence of a goal that still needs to
be refined into requirements
The software shall be reliable.
X
Source: Spencer Smith, McMaster U.
16
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Good & Bad
Standard
Pitfalls to Avoid
A Few Simple Tests
Summary & Tools
Typical Mistakes
• Noise = the presence of text that
carries no relevant information to
any feature of the problem
• Silence = a feature that is not
covered by any text
• Over-specification = text that
describes a feature of the solution,
rather than the problem
• Contradiction = text that defines a
single feature in a number of
incompatible ways
• Ambiguity = text that can be
interpreted in >=2 different ways
• Forward reference = text that refers
to a feature yet to be defined
• Wishful thinking = text that defines
a feature that cannot possibly be
validated
• Jigsaw puzzles = e.g., distributing
requirements across a document
and then cross-referencing
• Inconsistent terminology =
inventing and then changing
terminology
• Putting the onus on the
development staff = i.e. making the
reader work hard to decipher the
intent
• Writing for the hostile reader (fewer
of these exist than friendly ones)
Source: Steve Easterbrook, U. of Toronto
17
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Patterns for Functional Requirements:
Easy Approach to Requirements Syntax (EARS)
• A Ubiquitous requirement is continually active and takes the form The
<system name> shall <system response>
• A State-driven requirement is active while some precondition remains
true and takes the form WHILE <precondition> the <system name>
shall <system response>
• An Event-driven requirement is activated when a triggering event is
detected at the system boundary and takes the form WHEN <trigger> the
<system name> shall <system response>
• An Option requirement is used for systems that include a particular
feature and take the form WHERE <feature is included> the <system
name> shall <system response>
• An Unwanted Behavior requirement defines the required system
response to an unwanted external event and takes the form IF <trigger>
THEN the <system name> shall <system response>
• The basic EARS patterns can be combined to build Complex
requirements,
A. Mavin et al., Listens Learned (8 Lessons Learned
Applying EARS). RE’16, 276-282, IEEE CS, 2016
18
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Good & Bad
Standard
Pitfalls to Avoid
A Few Simple Tests
Summary & Tools
Quiz: Criticize these Requirements
X
Invoices, acknowledgments, and shipping notices shall X
The Order Entry system provides for quick, userfriendly and efficient entry and processing of all orders.
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.
The system shall be upgraded in one whack.
The system has a goal that as much of the IS data as
possible be pulled directly from the T&M estimate.
X
X
X
19
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Good & Bad
Standard
Pitfalls to Avoid
A Few Simple Tests
Summary & Tools
Sample Commercial Tool: RAT
• Requirements Authoring Tool (RAT)
• https://www.reusecompany.com/rat-authoring-tools
• Tools and plug-ins to assist you in the activity of writing requirements
and other natural language texts.
• Performs Correctness and Consistency analysis on the fly
• Suggests controlledvocabulary items based
on a central knowledge
base
• Integrated into
Requirements
Management Tools and
Modelling Tools
20
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
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!
21
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
How about Requirements
Specifications?
Requirements Specification
• Structured collection of the essential requirements
(characteristics, functions, qualities, constraints, and
attributes) of the system and its external interfaces
• Can target different levels of abstraction (business,
stakeholder, system, software…)
• Basis for contractual agreements between contractors or
suppliers and customers
• Help software customers accurately describe what they wish to obtain
• Help software suppliers understand exactly what the customer wants
• One place for all requirements and related information
• Useful for project management and evolution
23
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Requirements Specification Standards
• Different standards exist that provide guidelines and reusable
templates
• Make specifications more uniform in an organization and across
different organizations
• Encode many best practices
• Help address the needs of diverse readers (developers, clients,
testers, project managers, lawyers…)
• Help requirements engineers to:
• Develop a template (format and content) for the software requirements
specification (SRS) in their own organizations
• Develop additional documents such as SRS quality checklists or an
SRS writer’s handbook
24
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
About Standards…
• A standard is a “Set of mandatory requirements established
by consensus and maintained by a recognized body to
prescribe a disciplined uniform approach or specify a product,
that is, mandatory conventions and practices”
[ISO/IEC/IEEE 24765]
25
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
ISO JTC1-SC7 Standards & Technical Reports
http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_tc_browse.htm?commid=45086
26
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
ISO/IEC/IEEE 29148:2018 Standard
• ISO/IEC/IEEE 29148:2018: Systems and software
engineering — Life cycle processes — Requirements
engineering
• https://doi.org/10.1109/IEEESTD.2018.8559686
• Provides a unified treatment of the processes and products
involved in engineering requirements throughout the life cycle
of systems and software.
• Harmonizes IEEE 830, SWEBOK, and 7 other standards.
• Emphasis on characteristics of good requirements, RE
activities and processes, operations (and operation context),
and different information items (including their structures)
such as specification of requirements for businesses,
stakeholders, systems, and software.
27
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Business Requirements Specification Outline
The Business Requirements
Specification (BRS) describes the
organization’s motivation for why the
system is being developed or
changed, defines processes and
policies/rules under which the system
is used and documents the top-level
requirements from the stakeholder
perspective.
The BRS describes how the
organization is pursuing new business
or changing the current business in
order to fit a new business
environment, and how to utilize the
system as a means to contribute to the
business.
28
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Stakeholder Requirements Specification Outline
The Stakeholder Requirements
Specification (StRS) describes the
organization’s motivation for why the
system is being developed or
changed, defines processes and
policies/rules under which the system
is used and documents the top-level
requirements from the stakeholders’
perspective including expressing
needs of users/operators/maintainers
as derived from the context of use in a
specific, precise and unambiguous
manner.
In the context described in the BRS,
the StRS describes how the
organization will utilize the system as a
means to contribute to the business.
29
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
System Requirements Specification Outline
The System Requirements
Specification (SyRS) identifies the
technical requirements for the selected
system-of-interest and usability for the
envisaged human-system interaction.
It defines the high-level system
requirements from the domain
perspective, along with background
information about the overall
objectives for the system, its target
environment and a statement of the
constraints, assumptions and nonfunctional requirements.
30
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Software Requirements Specification Outline
The Software Requirements
Specification (SRS) is a
specification for a particular
software product, program, or set of
programs that performs certain
functions in a specific environment.
The SRS may be written by one or
more representatives of the
supplier, one or more
representatives of the acquirer, or
by both.
Note: The structure of section 3
may vary substantially
31
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
SRS Details: Section 1 (See Standard, Section 9.6)
Delineate the purpose of the
software to be specified.
• 1.
Introduction
• 1.1 Purpose
• 1.2 Scope
• 1.3 Product overview
• 1.3.1 Product perspective
• 1.3.2 Product functions
• 1.3.3 User characteristics
• 1.3.4 Limitations
• 1.4 Definitions
Describe the scope of the software (product to
be produced, what it will do, its goals,
application, and benefits…
Define the software’s relationship to the larger
system (if any) and to other related products.
Describe user/system/communication
interfaces, operations, site adaptation…
Provide a summary of the major functions that the
software will perform. Diagrams, scenarios, use
cases, and user stories may be used here.
Describe general characteristics of the intended
groups of users of the product, including those
that may influence usability (e.g., educational level,
experience, disabilities, and technical expertise)
Provide a general description of any other items that will limit
the supplier’s options, including: regulations/policies, hardware
limitations, interfaces, security/safety considerations,
physical/mental considerations…
32
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
SRS Details: Section 3 (See Standard, Section 9.6)
• 3 Requirements
Define the fundamental actions that have to take place in the
software in accepting and processing the inputs and in
processing and generating the outputs. Functional requirements!
• 3.1 Functions
Specify both the static and the dynamic numerical
requirements placed on the software or on human
interaction with the software as a whole.
• 3.2 Performance requirements
Define usability and quality in use requirements
and objectives for the software system.
• 3.3 Usability requirements
Define all inputs into and outputs from the
software system. Complement previous
information (do not duplicate)
• 3.4 Interface requirements
• 3.5 Logical database requirements
• 3.6 Design constraints
• 3.7 Software system attributes
• 3.8 Supporting information
Include:
a) Types of information used
b) Data entities and their relationships
Include:
a) Standards compliance
b) Accounting & Auditing procedures
Specify other required non-functional
requirements and quality attributes
(reliability, privacy, security…)
Other relevant information that can help!
Be explicit as to whether these are
required or not.
33
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
SRS Details: Section 4
Verification: This section
provides the verification
approaches and methods
planned to qualify the software.
The information items for
verification are recommended to
be given in a parallel manner with
the information items in section 3.
Was not present in older
standards such as IEEE 830.
34
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
A Good Requirements Specification Shall Be:
• Complete
• Consistent
• Specifies all the things the
system must do (including
contingencies)
• Does not contradict itself
(satisfiable)
• ...and all the things it must not do!
• Note: inconsistency can be hard
to detect, especially in
concurrency/timing aspects and
condition logic
• Conceptual Completeness
(e.g., responses defined for all
classes of input)
• Structural Completeness
(e.g., no TBDs in sections)
• Feasible
• Can be entirely realized and
validated within known
constraints (e.g., cost, schedule,
technical) with acceptable risk
• Avoid synonyms for terms
• Formal modeling can help
• Beneficial
• Has benefits that outweigh the
costs of development
• Modifiable
• Will have to be updated!
35
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Relevant Patterns… in French!
• From Hydro-Québec (with thanks to René Bujold)
• Excel file with hundreds of illustrated patterns based on the
structure of IEEE 830, including non-functional requirements
36
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Some Tools that Can Help You…
• Requirements Authoring Tool (RAT)
• Requirements Quality Analyzer (RQA Quality Studio)
• QVscribe (from QRA, in Halifax!)
• RAVEN
37
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Quiz
1.
Does IEEE 29148 impose standard templates for
requirements specifications?
2.
Whom are requirements specification documents meant
for?
3.
Can you enumerate two types of requirements
specifications?
4.
Can you enumerate three benefits of using a standard such
as ISO/IEC/IEEE 29148:2018?
5.
Can you think of potential problems related to the use of
such standards?
38
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot
Why Don’t VSEs Use Standards? (FYI Only)
VSE = very small entities:
enterprise, government, or not-forprofit organizations; departments;
or projects with up to people who
develop systems with hardware
and software components and/or
software products.
* Difficult, Bureaucratic, not enough guidance.
C.Y. Laporte and R.V. O'Connor: Software Engineering Standards for Very Small Entities:
Accomplishments and Overview. IEEE Computer, August 2016, 84-87
39
SEG3101. Writing Good Requirements and Specifications © 2009 G. Mussbacher, 2011-2021 D. Amyot