Writing Good Requirements

1
Writing Good Requirements
Presented By
Jerry Karasz Senior Computer Scientist Apogen
Technologies, Inc. jerry.karasz_at_apogentech.com

• Albuquerque SPIN Meeting
• September, 2005

2
Overview

• Definitions
• Requirements Analysis Overview
• Common Mistakes in Writing Requirements
• Good Requirements
• Good Sets of Requirements

3
Definition

• Stated Need a customer or users informal
  statement of what they would like the product to
  do. Sometimes referred to as a user input to
  requirements analysis.
• If you ask users what they need, they will
  sometimes
• be unable to describe the actual need they have.
• ask for something they dont really need.
• ask for the product to do something that is not
  consistent with the contract.
• ask for the product to do something that is not
  feasible given the available time and resources.

4
Definition

• Requirement a formal statement of a feature,
  function, or attribute of a product that must be
  implemented in order for the product to have the
  mandated value or worth for the user.
• In English, this means
• Until its written down, its not a requirement.
• If nobody is willing to specify it in detail,
  its not a requirement.
• If the product meets the users needs without it,
  its not a requirement.

5
Types of Requirements

• Functional Requirement any requirement that
  states what the system has to do, or what outputs
  should come from what inputs.
• Often, functional requirements
• map to a feature, function, or control in an
  application.
• represent tangible aspects of the product.
• are the easiest to identify and define.

6
Types of Requirements

• Non-Functional Requirement any requirement that
  describes the fitness of the system for use by
  end users, often in terms of the quality of the
  product.
• Often, non-functional requirements
• do not map to a feature, function, or control in
  an application.
• represent intangible aspects of the product.
• are difficult to identify and define completely.

7
Some Categories of Non-Functional Requirements

• Process Methodology Constraints
• Standard/Policy/Procedure Compliance
• Performance
• Maintainability/Supportability
• Safety
• Scalability
• Security
• Survivability
• Portability
• Memory Use/Storage Space (for software)

8
Where Do Requirements Fit In?
Analyst
Customer
Designer
Developer
Safety
Procedure
Requirement
Requirements Analysis
Physical Design
Policy
Design
Standard
Requirement (Derived)
Requirement (Derived)
Compatibility
Domain Expert
Requirements Specification
Test Plan Development
Stated Needs
Document
Test Plan
Process
9
Common Mistake 1

• Improper or imprecise terminology - avoid using
  the following words or phrases

• etc.
• and so on
• among others
• any
• several
• various
• and/or
• not limited to
• as well as
• or

• state of the art
• user-friendly
• easy
• simple
• rapid
• efficient
• improved
• optimal
• sufficient

10
More Words to Avoid

• And these

• safe
• reliable
• robust
• adequate
• acceptable
• normal
• proper
• reasonable

• appropriate
• suitable
• possible
• average
• timely
• typical
• secure
• optimum

11
Common Mistake 2

• Bad assumptions - can happen when
• no system documentation or user input exists. You
  make assumptions in order to proceed, and some of
  your guesses are wrong.
• system documentation or user input exists, but
  is not available to you. This can be caused by
  politics, bureaucratic red tape, or incompetence
  anywhere in the chain.

12
Common Mistake 3

• Forcing the design - requirements need to state
  what is needed, not how it is to be implemented.
  To avoid forcing the design, continually ask
  Why? This will often turn up the underlying
  needs that drove the original statement.

The start button shall be recessed. Why does it
have to be a button that starts the treadmill (as
opposed to a switch or knob)? Why does it need
to be recessed?
13
Common Mistake 4

• Specifying how the user will use the product
  rather than what the product should do for the
  user.
• Dont The user shall operate the treadmill
  only in an upright position. This is a
  requirement on the user, not the treadmill.
• Do The treadmill shall only run when it is in
  an upright position. This keeps the treadmill
  from operating in an unsafe condition.

14
Common Mistake 5

• Failing to assign responsibility for a
  requirement.
• Dont The treadmill shall be returned to a
  safe state whenever an error condition is
  encountered. This is in the passive voice, and
  doesnt identify who or what is responsible for
  returning the treadmill to a safe state.
• Do The treadmill shall return itself to a safe
  state whenever an error condition is encountered.

15
Common Mistake 6

• Over-specifying requirements.
• Dont All source code shall be reviewed by a
  safety engineer before inclusion in a release.
  This is overly restrictive. Only the safety
  critical portions of the code need to be subject
  to such stringent reviews.
• Do The source code for all safety critical
  functions shall be subjected to a formal
  inspection before inclusion in any release.

16
Hands-On SessionCommon Mistakes
The treadmill control module shall run on an
RT214 real-time processor.
Questions to ask Do we have to have a control
module? Why does the control function have to run
on an RT214 real-time processor? Better The
treadmill shall initiate emergency stop within
.03 seconds of detecting a critical error.
17
Hands-On SessionCommon Mistakes
The treadmill shall be used in a manner
consistent with BPC-243.5.7.
Questions to ask Isnt this a requirement
against the user, not the treadmill? Watch out
for references to external specifications or
guides try instead to write your own
requirements that capture the real
needs. Better The treadmill shall comply with
BPC-243.5.7, Section 8, dated 24 August,
2005. Best The treadmill shall power itself off
when its current flow reaches 90 of its
rated maximum.
18
Hands-On SessionCommon Mistakes
The treadmill shall have a sufficiently long ramp.
Questions to ask Sufficiently for what or
whom? Better The treadmill ramp shall be long
enough that a user can run at 10 mph with a
5.5-foot stride and not impact the treadmill
frame.
19
Hands-On SessionCommon Mistakes
The treadmill shall store the time and distance
traveled in a database after each session.
Questions to ask Why does it need to be stored
in a database? Could we store it in a file or in
Read-Only-Memory instead? Better When the
treadmill is powered on, it shall display the
time and distance traveled during the previous
session.
20
What Makes a Requirement Good?

• A good requirement is written clearly enough that
  you can implement it, and you will know when it
  has been done correctly.

• This means
• Not good requirements are still okay as inputs
  to requirements analysis.
• Once your project has finished requirements
  analysis, all of the requirements in the spec and
  any new ones you add need to be good.

21
Not Good Vs. Good
Analyst
Customer
Designer
Developer
Safety
Procedure
Requirement
Requirements Analysis
Policy
Design
Design
Standard
Requirement (Derived)
Requirement (Derived)
Compatibility
Domain Expert
Requirements Specification
Test Plan Development
Not Good Requirements
Document
Good Requirements
Test Plan
Process
22
Characteristics of a Good Requirement

• The characteristics of a good requirement are

• Correctness
• Necessity
• Clarity
• Focus
• Feasibility
• Verifiability
• Support Documentation

23
Characteristic 1 of a Good Requirement

• Correct A requirement has to be correct. The
  information used to create it has to be correct
  and has to reflect reality. In general, the
  development team is not going to know if the
  requirements are correct, so have another
  experienced analyst or engineer review the
  requirements with you before finalizing them.

24
Characteristic 2 of a Good Requirement

• Necessary A requirement has to be necessary. If
  it wasnt included, whats the worst that could
  happen? If you and the users are willing to
  accept those consequences, then it probably isnt
  really necessary.

25
Characteristic 3 of a Good Requirement

• Clear A requirement has to be clear and
  unambiguous. If it can be interpreted in more
  than one way, then the product is indeterminate
  (you dont know exactly what youre building),
  and youll never know when youre done.

26
Clarity in a Requirement

• Three words to use carefully
• Shall specifies a feature or function that is
  required in the product and which the product
  development team must provide. REQUIREMENT
• Will predicts the existence of a feature or
  function in the product, but does not identify
  who is responsible for developing it. FACT
• Should specifies a desired or optional feature
  or function of the product. The product
  development team can choose not to implement the
  feature or function and still develop an
  acceptable product. CONSTRAINT or SUGGESTION

27
Examples

• Shall The maximum speed of the treadmill shall
  be 10 mph. The treadmill must be built to
  enforce this limit.
• Will The treadmill speed will not exceed 10
  mph. This is a statement of fact no one is
  responsible for this happening.
• Should The treadmill speed should not exceed
  10 mph. The treadmill can be built to exceed
  this limit if it has to, but it would be better
  if it did not.

28
More Clarity in a Requirement

• Write requirements simply and use the language of
  the problem domain so that users can tell you if
  theyre correct or not. To insure clarity
• do formal inspections of the requirements.
• whenever possible, write high-level test cases to
  accompany any requirements you want to add.

29
Characteristic 4 of a Good Requirement

• Focus A requirement has to focus on one thing.
  Dont write one requirement that specifies
  multiple needs instead, break it up into
  several requirements.

• Dont The meter shall display a minimum of
  -999 and a maximum of 999 volts.
• Do The meter shall display a minimum value of
  -999 volts. and The meter shall display a
  maximum value of 999 volts.

30
Characteristic 5 of a Good Requirement

• Feasible A requirement must be feasible. If you
  cannot implement it with the budget, schedule,
  resources, and other limitations that are
  available to your project, then either it must be
  dropped or the project has already failed.
  Designers and developers need to work with the
  requirements analysts to figure this out.

31
Characteristic 6 of a Good Requirement

• Verifiable A requirement has to be testable.
  Once a solution for a requirement has been
  implemented, you need some way to know if the
  design and implementation are correct. If you
  cant test the requirement, then the product is
  indeterminate you cant prove that what you
  built is right, and you may never get acceptance
  from the customer.

32
Characteristic 7 of a Good Requirement

• Supporting Documentation Every requirement
  should include the supporting information that is
  appropriate for your organization and project.
  Ask for a template before you begin, or use
  existing requirements as an example (either from
  this project or from a similar one).

33
Examples of Supporting Documentation

• The originator where did this requirement come
  from? If there are questions during design or
  implementation, who will you talk to? The
  originator should include the name and title of
  the person or document that was the original
  source.
• The originators priority what priority does
  he/she give to each of the requirements they
  provided?

34
Examples of Supporting Documentation

• Explanatory comments what does the development
  team need to know in order to understand this
  requirement? Include text that expands
  operational details, translates obscure language,
  or further explains the conditions that make the
  requirement needed.
• The origination date when was the requirement
  first created?

35
Hands-On SessionGood Requirements
The treadmill shall run on 10 or 220 VAC power.
Questions to ask Is this a typo? Shouldnt it be
110 or 220? Better The treadmill shall run on
110 or 220 VAC power.
36
Hands-On SessionGood Requirements
The treadmill shall have 3-inch thick BU47 foam
padding covering the frame and control panel to
reduce the damage of any impact.
Questions to ask Is this really necessary? Can
you use the treadmill with this in place? Will
anyone buy it? Better Get rid of this
requirement.
37
Hands-On SessionGood Requirements
The treadmill shall support a maximum load of
three.
Questions to ask Three what? This is ambiguous
and unclear. Better The treadmill shall support
a maximum power load of three watts.
38
Hands-On SessionGood Requirements
The treadmill shall not start unexpectedly.
Questions to ask Unexpectedly? If it works as
designed, but starts when the user increases the
velocity setting (even though the on/off switch
is off), is that unexpected? Better The
treadmill shall never start when the power
control is set to off.
39
Hands-On SessionGood Requirements
The treadmill shall run continuously for 5,000
hours at 5 mph without failing.
Questions to ask How are we going to test this?
Is it possible? Is it necessary? Better The
treadmill shall have a Mean Time Between Failure
(MTBF) of less than X with . . .
40
Collections of Requirements

• Requirements that have been gathered together
  into a requirements specification must meet some
  special conditions in order to be considered a
  set of good requirements

• Complete
• Consistent
• Updateable
• Traceable
• Prioritized

41
Characteristic 1 of a Set of Good Requirements

• Complete The set of requirements must be
  complete. If requirements are missing, then the
  product will also be incomplete. It is likely
  that the missing requirements will turn up at
  inopportune times and cause problems throughout
  the project life cycle.

42
How Do We Find Missing Requirements?

• One way to find missing requirements is to have a
  checklist of the kinds of requirements you have
  created on similar projects, or to which similar
  systems are subject. As you review this list, you
  will discover missing requirements.
• Having domain experts review your requirements
  with you will also help.

43
Characteristic 2 of a Set of Good Requirements

• Consistent The set of requirements must be
  consistent. If there are requirements in your
  specification that conflict with each other, then
  the product will not be able to meet all of your
  requirements. Inconsistencies must be resolved in
  order for your project to succeed.

44
Characteristic 3 of a Set of Good Requirements

• Updateable - They must be updateable. If you have
  to change a requirement (create, edit, or
  delete), you must be able to evaluate the impact
  of that change on all of the other requirements.
• Organize your requirements into categories by
  their scope or purpose. When one requirement is
  changed, similar requirements are most likely
  close at hand.

45
Characteristic 4 of a Set of Good Requirements

• Traceability The set of requirements must be
  traceable. You must be able to tie a derived
  requirement back to its origin, and you must be
  able to trace a requirement to the
  hardware/software that implements it, as well as
  to the test cases that verify it. The
  traceability to test cases tells you if you have
  tested your product against each requirement.

46
Characteristic 5 of a Set of Good Requirements

• Prioritization Each requirement has to be
  ranked against the others according to its
  implementation importance. You cant have
  everything be a top priority.
• If you cant prioritize a requirement, it cant
  be assigned to a specific product release.

47
Treadmill Beast Example

• The Beast was analyzed by a group of System
  Safety Interns at the US Army Facility at
  Texarkana, TX during a Software Safety Course in
  2004.
• The following requirements were derived based
  upon their analysis of the Beast.
• No judgment of good was made at that time.

48
Treadmill Safety Requirements
EXAMPLE Human Interface

• The Beast shall stop immediately upon emergency
  stop.
• The emergency stop shall be executed by a button
  and a tether.
• The handrails shall be the appropriate shape and
  diameter so to maximize gripping ability.
• The front handrail shall be sufficiently padded.
• The buttons of the human interface shall be
  appropriately colored for ease of operation.
• The Beast shall have a written safety warning on
  the control panel indicating of the health
  hazards of the system.
• The Beast shall have a user chart to find the
  appropriate maximum heart rate.
• The control panel shall display an error message
  in the event of a sensor failure.
• A training and procedures manual shall be
  provided with the Beast that indicates proper
  use/maintenance environments, care, physical
  hazards and user health criteria for use of the
  system.

49
Treadmill Safety Requirements
EXAMPLE Hardware Part 1

• The Beast shall stop and start rotation of the
  belt gradually.
• The Beast shall only allow forward motion of the
  belt.
• The Beast shall have an adequately strong frame.
• The Beast shall have a kick-plate protecting the
  motor.
• The belt shall provide adequate friction to the
  user and be constructed so to minimize wear and
  tear.
• The Beast shall be equipped with a grounding
  system.
• The screw drive shall increase and decrease
  inclination gradually in increments of .5 inches.
• The emergency stop shall automatically shutdown
  the motor.
• The emergency stop button shall be within the
  reach of the user.
• The Beast shall be equipped with fuses that break
  so to prevent excess current.
• The track shall have an inclination limit of 45o.

50
Treadmill Safety Requirements
EXAMPLE Hardware Part 2

• The start button shall be recessed so to prevent
  accidental activation.
• The Beast shall have a thermal sensor to prevent
  motor overheating.
• The belt shall be aligned by mechanical means.
• A backup battery shall be implemented in case of
  power failure to gradually slow down motor.

51
Treadmill Safety Requirements
EXAMPLE Software Part 1

• The software shall gradually stop the belt
  rotation upon program completion or manual stop.
• The Beast shall fail off (motor off).
• When the belt tension or power sensors indicate
  an unacceptable state.
• When emergency stop is activated.
• When entanglement sensor indicates an
  unacceptable state.
• The program select option when not functioning
  properly shall automatically default to manual
  mode.
• The maximum speed of the beast shall not exceed
  10 mph.
• The software shall gradually initiate the belt
  rotation upon user command.
• The Beast will provide a countdown/warning
  preceding belt rotation.

52
Treadmill Safety Requirements
EXAMPLE Software Part 2

• The user-controlled speed shall increase/decrease
  in increments of .2.
• A gradual stop shall be initiated when the user
  heart rate equals the maximum heart rate input.
• The CPU shall shutdown when emergency stop is
  executed.
• The software shall continually compare the heart
  sensors output and the maximum heart rate input
  when the fingertip sensor is engaged.
• The software shall return to initial settings in
  the event of power loss.
• When the sensors detect incorrect signals the
  software shall return to default state.
• The Beast shall go to a power save mode after a
  certain idle time has been reached to prevent
  motor overheat.

53
Summary

• Whenever possible,
• Submit vague or general inputs early in the life
  cycle, before requirements analysis.
• After requirements analysis, write good
  requirements that take into account the existing
  requirements specification.
• Provide test cases and testing guidelines with
  your requirements.
• Get others to review your work before you submit
  it.

54
Bibliography

• Writing Good Requirements, Karl Wiegers,
  Published in Software Development Magazine, May
  1999, http//www.cs.bgu.ac.il/elhadad/se/requirem
  ents-wiegers-sd-may99.html.
• Writing Good Requirements (A Requirements Working
  Group Information Report), Ivy Hooks, Published
  in Proceedings of the Third International
  Symposium of the INCOSE, Volume 3, 1993,
  http//www.itmweb.com/essay543.htm.
• Writing good requirements is a lot like writing
  good code, Jim Heumann, IBM, 30 June 2004,
  http//www-106.ibm.com/developerworks/rational/lib
  rary/5170.html.
• Effective Requirements Practices, Ralph R. Young,
  Addison-Wesley, February 2004.
• Meeting the Challenges of Requirements
  Engineering, Bill Thomas, Published in SEI
  Interactive, March, 1999, http//www.sei.cmu.edu/n
  ews-at-sei/features/1999/mar/Spotlight.mar99.pdf
• Software Engineering Spring 2005 Lecture 4, New
  York University, Published on the web Spring
  2005, http//www.cs.nyu.edu/courses/spring05/V22.0
  474-001/lec/lec4_h4.pdf