Writing Objectives and Requirements
1
CONTENTS
•
•
•
•
•
•
Module 1: Different Kinds of Requirements
Module 2: Characteristics of Good Requirements
Module 3: Requirements Writing Tips
Module 4: Practice Exercises
Module 5: Back to Our Case Study
Appendix: The Inherent Difficulty of Requirements
2
MODULE 1
Different Kinds of Requirements
3
What are Requirements?
“Requirements are … a specification of what should be
implemented. They are descriptions of how the system
should behave, or of a system property or attribute. They
may also include constraints on the development process of
the system.”
[Sommerville and Sawyer, 1997]
4
Different Types of Requirements
•
•
•
•
•
•
•
Business Requirements
User Requirements
Functional Requirements
Business Rules
Quality Attributes
External Interfaces
Design & Implementation Constraints
System
Requirements
Specification
[Adapted from K. Wiegers, More about Software Requirements]
5
Business Requirements
• Business requirements capture the business need and rationale for the
proposed project.
• Business requirements tells us why -- at the business level -- we’re doing
the project.
• They should state, or at least contain implicitly, the benefits the
sponsoring business organization expects to derive from a successful
project.
Example: The new InvestNow equity management system will better
serve our low-end equity investors (those with portfolios under $50K) by
allowing them to manage their own equity portfolios online. This selfservice system will provide more timely service to these investors and also
save the company money through the reduction of staff currently required
to manage these accounts.
6
User Requirements
• User requirements capture what the user will be able to do and
accomplish with the finished product.
• These requirements are defined by the goals and tasks that the users must
be able to perform using the product.
• User requirements are driven by the business requirements. In other
words, if the user requirements are satisfied, this should ensure the
attainment of the business requirements.
Example: Users of the InvestNow equity management system will be able
to 1) view their portfolio, 2) manage their account profile, 3) receive onscreen information about companies they currently invest in, 4) receive
on-screen information about companies they are considering making
investments in, and 5) buy and sell shares of stock within the limits set by
their account profile.
7
Functional Requirements
• Functional requirements describe what the developer is supposed to build.
• Functional requirements specify what the system will do or what it will allow
the user to do.
• These requirements are driven by the business and user requirements, but
they go a step further by describing what the system will do to satisfy those
higher-level requirements.
Example: The system will allow the user to request to view his or her
account profile. Upon this request, the system will display the current
profile. The user will then be allowed to edit any user-editable fields in the
profile. The edited profile will then be presented to the user for approval
before the changes are actually made to the stored profile.
etc. …
8
•
Business
Rules
Business rules include corporate policies, government regulations,
industry standards, and specified computational methods.
• Business rules typically have an existence outside the specific boundaries
of individual software projects and could be considered enterprise-level
assets.
• Business rules are not software requirements per se, but they often
require software elements to ensure that the system complies with these
rules.
Examples:
Only those customers whose total portfolio value is less than or equal to
$50,000 will be allowed to utilize the InvestNow system. Investments
made using InvestNow that would push the portfolio value beyond
$50,000 are not allowed.
Commissions on trades made within InvestNow are to be calculated
utilizing the company’s ComRate25 commission table.
9
Quality Attributes
• Quality attributes describe the product’s characteristics in ways that are
important to users, developers, or those who will maintain the system.
• Such characteristics might involve availability, performance, usability,
robustness, reliability, and similar attributes.
• Quality attributes should be stated precisely and succinctly and where
possible they should be quantified.
Examples:
For user editing of account profiles, drop-down menus, radio buttons and
similar methods should be used where possible to make editing more
convenient and to reduce user input errors.
A user request to view his or her portfolio summary should be satisfied in
less than 5 seconds.
10
External/Internal Interfaces
• Interfaces between the proposed system and other existing systems
(hardware or software) or the external world should be specified.
• When human user interfaces are a part of the proposed system, these
should be specified where possible using prototypes that have been
approved by the appropriate human user representatives.
Examples:
All account profile information will continue to reside within the existing
SI_Accounts DB2 database.
All requests from users for investment company information will be
satisfied by accessing the Investor_Inform service to which the company
subscribes.
The basic forms of the graphical user interfaces for the system are
specified in Prototype IN101v4.
11
Design and Implementation Constraints
• Design and implementation constraints are restrictions imposed on the
proposed system for some legitimate reason.
• These constraints might include technical features, tools to be used,
languages to be used, development standards, and so on.
Examples:
To access the SI_Accounts database, the system will utilize the existing
DB2 access modules: IN_ACC#233v1 and OUT_ACC#765v8.
Any changes to the SI_Accounts database must be approved by the DBA
and the Chief Design Architect.
Current organizational standards require that all coding for the InvestNow
system will be done in the Java programming language unless explicit
permission to do otherwise is obtained from the Chief Design Architect.
12
Relationships Among Types of
Requirements
Business
Requirements
Business
Rules
User
Requirements
Quality
Attributes
External/Internal
Interfaces
Functional
Requirements
Design and
Implementation
Constraints
System Requirements Specification
13
Relationships Among Types of
Requirements
Business
Requirements
Business
Rules
User
Requirements
Quality
Attributes
External/Internal
Interfaces
Functional
Requirements
Design and
Implementation
Constraints
Systems
Analysis
System Requirements Specification
(Scope Document)
14
•
•
•
•
Goals, Objectives and Requirements
A project comes into existence to do something: to have the end result - effect
some change. This is nearly always expressed in the language of the sponsor's
business. For example, the result of a web development project might be to
increase sales or to implement customer self-service. We call these Project Goals,
and meeting these goals is the primary focus of the project sponsor. Project goals
capture the intended fulfillment of a stated business need.
The project exists to produce accomplishments that do fulfill the stated goals.
These accomplishments, which should be measurable, we typically call Project
Objectives. These are the things that the project directly produces: an eCommerce
site; a web-enabled self-service application, etc. Accomplishing the project
objectives should ensure that the project fulfills the stated goals.
So what are Requirements? Requirements are the necessary specific outcomes
that are required to realize the objectives - and that the project therefore must
deliver.
To put it another way, requirements are the detailed view of the project objectives.
Because requirements are the things that the project must deliver, they are the
absolute definition of whether the project has achieved its objectives (and thus
fulfilled its goals).
Adapted from Introducing Project Requirements, by Martin Burns, www.evolt.org.
15
Project Objectives
• Project objectives are generally created at a higher level than the actual
project business requirements.
• Objectives are usually written first, and then refined into the actual
business requirements.
• Objectives are then in a sense just high-level requirements, and thus they
must be constructed with the same care and attention to detail as the
business requirements themselves.
• In the Modules that follow then, most of what we say about requirements
will also apply to objectives.
• The main difference is that the business requirements, being much more
detailed, will require even closer and more careful scrutiny at a detailed
level than objectives.
• The following modified diagram captures this relationship between
objectives and requirements.
16
drive
Project
Objectives
High-level Business Goals/Needs
refined by
Business
Requirements
Business
Rules
User
Requirements
Quality
Attributes
External/Internal
Interfaces
Functional
Requirements
Design and
Implementation
Constraints
System Requirements Specification
17
MODULE 2
Characteristics of Good Requirements
18
The Requirements Analysis Process
Reviewed
The Foundation for
the Entire Project
Problem
Fuzzy
Ambiguous
Ill-defined
Unstable
Business
Requirements
Problem Defined
Solution Envisioned
Business Outcomes
Articulated
System
Requirements
Rigorous
Precise
Unambiguous
Foundation for Design
19
Setting the Right Foundation
• Many software requirements documents are filled with
badly written requirements.
• Because the quality of any product depends on the
quality of the raw materials fed into it, poorly written
requirements are unlikely to lead to excellent software.
• In this Class/Workshop we will explore what constitutes a
good set of requirements and consider some best
practices for writing just that.
20
What Makes a Good Requirement?
• How can we distinguish a good requirement from those
that have problems?
• Wiegers and others have identified five basic
characteristics individual requirement statements should
exhibit.
• Each requirement should be:
–
–
–
–
–
Correct
Feasible
Necessary
Unambiguous
Verifiable (Testable)
Much of the material in this Module is adapted from the
article Writing Quality Requirements by Karl Wiegers
published in Software Development, May 1999.
Each Requirement Should Be Correct
• Each requirement must accurately describe the
functionality to be delivered.
• The checkpoint for correctness is the source of the
requirement -- the actual customer.
• Only the customers can determine the correctness of
functional requirements, which is why it is essential to
include them in the development of the requirements.
• Requirements inspections that do not involve customers
can lead to developers saying, "That doesn’t make sense.
This is probably what they meant.“ Not a good outcome.
22
Each Requirement Should Be Feasible
• It must be possible to implement each requirement within
the known capabilities and limitations of the system and its
environment.
• To avoid infeasible requirements, someone knowledgeable
about the system capabilities should work with the
requirements analysts in the requirements development
process.
• Such a person can provide a reality check on what can and
cannot be done technically, as well as to what can be done
only at excessive cost or other tradeoffs.
23
Each Requirement Should Be
Necessary
• Each requirement should document something the
customers really need or something that is required for
conformance to an external requirement, an external
interface, or a standard.
• Another way to think of "necessary" is that each
requirement originated from a source you recognize as
having the authority to specify requirements.
• If you cannot identify the origin and verify the authority
behind the requirement, it may be an example of
unnecessary "gold plating".
24
Each Requirement Should Be
Unambiguous
• The reader of a requirement should be able to draw only one
interpretation from it.
• In addition, multiple readers of a requirement should arrive at
the same interpretation.
• Natural languages like English are highly prone to ambiguity.
• To help avoid ambiguity, we should avoid subjective words
like user-friendly, easy, simple, fast, efficient, several, state-ofthe-art, world-class, improved, maximized, and minimized.
• We should strive to write each requirement in succinct,
simple, straightforward language of the customer domain,
not in computerese.
25
Each Requirement Should Be Verifiable/Testable
• For each requirement you should be able to devise tests or
use other verification approaches, such as inspection or
demonstration, that will clearly determine whether or not
each requirement is properly implemented in the product.
• If a requirement is not verifiable, determining whether it was
correctly implemented will become a matter of opinion and
no doubt contention, leading to an unhappy implementation.
26
What Makes a Good Requirements
Document?
• On the previous slides we identified five characteristics that each
individual requirement should have.
• There are also characteristics that the set of requirements (captured
in the requirements document) should possess.
• A Requirements Document should be:
– Complete
– Consistent
– Modifiable
– Traceable
27
A Requirements Document Should Be Complete
• No requirements or necessary information should be missing.
• Note that it is hard to spot missing requirements because they aren’t
there.
• To help with this it is very important to organize the requirements
hierarchically to help reviewers of the requirements document understand
the structure of the functionality described, so it will be easier for them to
tell if something is missing.
• If you focus on user tasks rather than on system functions during
requirements development, you are less likely both to overlook
requirements and to include unnecessary requirements.
• The Use Case method we described in an earlier course works well for this
purpose.
• If you know you are lacking certain information, use "TBD" ("to be
determined") as a standard flag to highlight such gaps. All TBDs should be
resolved before you proceed with construction of the relevant part of the
product.
28
A Requirements Document Should Be Consistent
• A consistent requirements document contains a set of requirements
that do not conflict with one another or other software
requirements.
• Disagreements among requirements must be resolved before
development can proceed.
• When you find inconsistent requirements, you may not know which
(if any) is correct until you do some research.
• Caution: Be very careful when modifying the requirements
document, because inconsistencies can slip in undetected if you
review only the specific change and not any related requirements
(the equivalent of regression testing for system changes).
29
A Requirements Document Should Be Modifiable
• As we will see shortly, change in requirements documents is
inevitable.
• Thus, you must be able to revise the requirements document when
necessary and maintain a history of changes made to each
requirement.
• This means that each requirement must be uniquely labeled and
expressed separately from other requirements so you can refer to it
unambiguously.
• You can make a requirements document more modifiable by
organizing it so that related requirements are grouped together,
and by creating a table of contents, index, and cross-reference
listing.
30
A Requirements Document Should Be Traceable
• Each requirement in the requirements document should be linkable
(traceable) to its source.
• Each requirement should also be linked to the design elements,
source code, and test cases that are constructed to implement and
verify the requirement as the project progresses.
• Traceable requirements must be uniquely labeled and written in a
detailed and structured way, as opposed to large, narrative
paragraphs or bullet lists.
31
MODULE 3
Requirements Writing Tips
32
The Requirements “Problem”
33
Success Rate for IT Projects
•
•
•
Project is a success: The project is
completed on-time and onbudget, with all features and
functions as initially specified.
Project is challenged: The project
is completed and operational, but
over-budget, over the time
estimate, or offers fewer features
and functions than originally
specified.
Project a failure: The project is
canceled at some point during the
development cycle.
1994 CHAOS Report,
Standish Group survey of
1994
360 ITYExecutives
representing over 8,000
projects.
53%
Success
Challenged
16%
31%
Failure
34
Success Rate for IT Projects – Some
Progress
Standish Group surveys (2002 survey represents over 40,000 projects)
35
What Challenges IT Projects?
 When the original Standish Group survey asked each executive IT
manager to identify the most important factor that caused projects
to be challenged (over budget or schedule, or both), the top three
factors listed were:
1. Lack of user input
2. Incomplete requirements
3. Changing requirements
13%
12%
12%
36
What Challenges IT Projects? (cont’d)
 The Standish Group survey isn’t the only study to show the critical
role of requirements in software development
 The European Software Process Improvement Training Initiative
(ESPITI) conducted a survey in which respondents were asked to
identify the relative importance (major, minor, or not a problem) of
various types of issues in the software process
 The ESPITI survey, based on almost 4,000 responses, revealed the top
two factors cited as major problems were:
1. Requirement specifications
2. Managing requirements
50% cited as a major problem
42% cited as a major problem
37
The Critical Importance of Good
Requirements: An Example
• In 2004, the FBI’s planned new automated case management
system was abandoned after $170 million had been spent on
its development!
• One of the authors of the U.S. General Accounting Office
(GAO) report on the failed project summarized its difficulties
as follows (underlining added):
It was a classic case of not getting the requirements
sufficiently defined in terms of completeness and
correctness from the beginning. And so it required a
continuous redefinition of requirements that had a
cascading effect on what had already been designed and
produced.
[From Goldstein, 2005]
38
Writing is an Art, Not a Science
• There is no algorithmic way to write excellent
requirements. It is largely a matter of experience and
learning from the requirements problems you have
encountered in the past.
• On the following slides are a few guidelines to keep in
mind as you document software requirements.
Much of the material in this Module is adapted from the
article Writing Quality Requirements by Karl Wiegers
published in Software Development, May 1999.
39
Some Requirements Writing Guidelines
•
•
•
•
•
Write complete sentences.
Keep sentences and paragraphs short.
Use the active voice.
Use proper grammar, spelling, and punctuation.
Use terms consistently and define them in a glossary or
data dictionary.
40
Some Requirements Writing Guidelines (cont’d)
• To see if a requirement statement is sufficiently well
defined, read it from the test designer’s and system
analyst’s perspective.
• Ask if you need additional clarification from the
requirements author to understand the requirement well
enough to test it?
• If so, that requirement should be elaborated before
proceeding.
41
Some Requirements Writing Guidelines (cont’d)
• Requirement authors often struggle to find the right level
of granularity. Avoid long narrative paragraphs that contain
multiple requirements.
• A helpful granularity guideline is to write individually
testable requirements. If you can think of a small number of
related tests to verify correct implementation of a
requirement, it is probably written at the right level of
detail.
• If you envision many different kinds of tests, perhaps
several requirements have been lumped together and
should be separated.
42
Some Requirements Writing Guidelines (cont’d)
• Watch out for multiple requirements that have been
aggregated into a single statement.
• Conjunctions like "and" and "or" in a requirement suggest
that several requirements have been combined.
• Never use "and/or" in a requirement statement. In other
words, “A and/or B” should be replaced with “A or B, or
both”.
43
Some Requirements Writing Guidelines (cont’d)
• Write requirements at a consistent level of detail throughout the
document. Here’s an example of such inconsistency. Suppose
these two requirements were found in the same requirements
document.
– "A valid color code shall be R for red" and "A valid
color code shall be G for green" have been split out
as separate requirements (VERY DETAILED)
– While in the same document you find: "The
product shall respond to editing directives entered
by voice" meant to describe an entire subsystem,
not a single functional requirement. (VERY HIGHLEVEL)
44
Some Requirements Writing Guidelines (cont’d)
• Avoid stating requirements redundantly in the
requirements document.
– While including the same requirement in
multiple places may make the document easier
to read, it also makes maintenance of the
document a nightmare.
– The multiple instances of the requirement all
have to be updated at the same time to prevent
an inconsistency creeping in.
– If you must have multiple references to the
same requirement, write it once, and refer to it
by number or name.
45
Writing is More Art Than Science
• While there is no silver bullet, your requirements will
improve drastically if you will:
– Observe the guidelines given here.
– Review the requirements formally, informally,
early, and often.
– Involve customers in a meaningful
requirements partnership.
– Consult testers and developers as needed for
feasibility as well as clarity.
46
Walkthroughs: Validating
Requirements
• Before proceeding to design, it is crucial to validate:
– That the requirements are correct and complete
– That the requirements are testable
– That you understand the relevant quality and
performance attributes
– That you understand implementation priorities
– That all customer needs have been
addressed
• This is typically done using walkthroughs
47
MODULE 4
Practice Exercises
48
Example #1
• In your group analyze the following requirement, taken from an
actual requirement document, against the five characteristics of a
good requirement (listed below for reference).
"The product shall provide status messages at regular
intervals not less than every 60 seconds."
Each requirement should be:
* Correct
* Feasible
* Necessary
* Unambiguous
* Verifiable
The material in this Module is adapted from the article
Writing Quality Requirements by Karl Wiegers published
in Software Development, May 1999.
49
Example #1: Possible Resolution
"The product shall provide status messages at regular
intervals not less than every 60 seconds."
• This requirement is incomplete: what are the status messages and how
are they supposed to be displayed to the user?
• The requirement contains several ambiguities. What part of "the product"
are we talking about? Is the interval between status messages really
supposed to be at least 60 seconds, so showing a new message every 10
years is okay? Perhaps the intent is to have no more than 60 seconds
elapse between messages; would 1 millisecond be too short? The word
"every" just confuses the issue.
• As a result of these problems, the requirement is not verifiable.
50
Example #1: Possible Resolution (cont’d)
"The product shall provide status messages at regular
intervals not less than every 60 seconds."
Here is one way we could rewrite the requirement to address its shortcomings:
1. Status Messages.
1.1. The Background Task Manager shall display status messages in a
designated area of the user interface at intervals of 60 plus or minus 10
seconds.
1.2. If background task processing is progressing normally, the percentage of
the background task processing that has been completed shall be displayed.
1.3. A message shall be displayed when the background task is completed.
1.4. An error message shall be displayed if the background task has stalled.
Splitting this into multiple requirements makes sense because each will require separate
test cases and because each should be separately traceable. If several requirements are
strung together in a paragraph, it is easy to overlook one during construction or testing.
51
Example #2
• In your group analyze the following requirement, taken from an
actual requirement document, against the five characteristics of a
good requirement (listed below for reference).
"Charge numbers should be validated on-line against the
master corporate charge number list, if possible."
Each requirement should be:
* Correct
* Feasible
* Necessary
* Unambiguous
* Verifiable
52
Example #2: Possible Resolution
"Charge numbers should be validated on-line against the
master corporate charge number list, if possible."
• Incomplete. What does "if possible" mean? If it’s technically feasible? If
the master charge number list can be accessed on line?
• Ambiguous. We should avoid imprecise words like "should." The
customer either needs this functionality or he doesn’t.
Here is a possible improved version of this requirement:
The system shall validate the charge number entered against the on-line
master corporate charge number list. If the charge number is not found
on the list, an error message shall be displayed and the order shall not
be accepted.
53
MODULE 5
A Case Study
54
Case Study
We will revisit Case Study #1 – to create a Web site
to automate seminar registrations.
We will write, and then analyze business
requirements for the proposed
55
Team Activity
Consider a proposed new online system to automate
seminar registration for a company that offers seminars at
multiple sites and on multiple dates. Here are some features
of the proposed system that were gathered at an initial onehour meeting with the customer:

Seminar registration is now handled by mail or by phone, based on seminar
brochures sent out in the mail. The customer wishes to implement an online (webbased) enrollment system.

A potential seminar enrollee should be able to go to the new web site, select a
specific seminar and then pay for and enroll in it if space is available.

Payment would be made by online credit card transaction. The payment
information and transaction approval is currently handled by the corporate financial
system.

The system should send an email reminder to each paid participant a week before
the seminar is scheduled for delivery.

The seminar manager requested a new daily report showing the current status of
enrollment for all seminars being offered.
56
Context DFD
Attendee Data Store
seminar_reminder
Email Sys
seminar_reminder
registration_decline
attendee_information
confirmation_of_cancellation
catalog_search_req
Seminar
Attendee
registration_req_w_cc
payment_info
Proposed
System
credit
action
Corporate
Financial System
cancellation_req
confirmation_of_seat
Seminar Mgr
confirmation_of_cc_pmt
seminar_information
search_results
Seminar Data Store
Appendix
The Inherent Difficulty of Requirements
58
Requirements Development is a Difficult Task
• Developing requirements is quite simply a difficult task, and there are
very good reasons for this.
• Some of these reasons are simply a part of the requirements
development world and we must learn to deal with them since they
cannot be removed.
• The following slides document what we call the Seven Principles of
Requirements which capture the essence of the requirements
development challenge.
• Principles #5 and #6 are particularly hard for us to accept sometimes,
but accept them we must because they are immutable.
• However, acceptance does not mean “give up,” but rather it encourages
us to be realistic while doing the very best job we can on an admittedly
difficult task.
59
Requirement Principle #1
Bad requirements lead to unsuccessful projects.
Requirements drive all other aspects of a project. If the requirements
are incorrect or incomplete, no matter how perfectly the design and
implementation are conducted, the results will not meet customer
expectations.
[This appendix is adapted from K. Wiegers, More about Software Requirements]
60
Requirement Principle #2
Requirements must be discovered, not just gathered.
Customers will not think of everything they need to tell you, nor will
they be able to communicate easily everything they intend to
communicate. Customers may not even have a good understanding of
the problem they are seeking to solve. The analyst should view himself
or herself as a consultant and a problem solver, whose job is to help the
customer to discover the true problem to be solved and what a good
solution would entail.
61
Requirement Principle #3
Requirements discovery is a process not an event.
Requirements discovery is an iterative process. You must articulate
requirements then validate them with the customer, then repeat the
whole process. Taking things at face value after one customer meeting
or communication is a sure way to produce incorrect and incomplete
requirements, and may even lead to an attempt to solve the wrong
problem completely.
62
Requirement Principle #4
Good requirements demand customer involvement.
No project will be successful if the customer’s expectations aren’t met;
customer expectations can’t be meet if they aren’t well-understood; only
the customer will be able to articulate his or her true expectations.
63
Requirement Principle #5
Requirements are never perfect.
Requirements discovery is a difficult iterative process. At some point,
the requirements must be baselined, so design can begin. Just accept
that there will always be something forgotten or misunderstood no
matter how long you take to discover the requirements. Make your best
effort within the time your project allots and move on, knowing that
some changes may be necessary as you learn more later. Don’t fall into
analysis paralysis waiting for the perfect set of requirements to appear.
64
Requirement Principle #6
Change in requirements is inevitable.
Because requirements are never perfect, we must accept the
inevitability of change as we and the customer discover new insights
about the requirements as the project progresses. Gain acceptance from
the customer of a viable and reasonable change control process at the
beginning of the project instead of making the unrealistic assumption
that the requirements are finalized when baselined.
65
Requirement Principle #7
Develop a requirements partnership.
Because requirements are never perfect and change is inevitable,
successful projects emerge from a partnership built on mutual trust and
understanding between analysts, developers, and customers. Do your
part to establish and nurture this partnership by providing realistic
estimates and commitments throughout the project and displaying
flexibility when the inevitable changes occur. Help customers
understand their role in establishing such a partnership as well.
66