Writing Good Requirements - PowerPoint PPT Presentation

Loading...

PPT – Writing Good Requirements PowerPoint presentation | free to view - id: 91432-NDQyY



Loading


The Adobe Flash plugin is needed to view this content

Get the plugin now

View by Category
About This Presentation
Title:

Writing Good Requirements

Description:

Designer. Developer. Safety. 22. Characteristics of a Good Requirement ... Designers and developers need to work with the ... Collections of Requirements ... – PowerPoint PPT presentation

Number of Views:2079
Avg rating:5.0/5.0
Slides: 55
Provided by: jerryk1
Category:

less

Write a Comment
User Comments (0)
Transcript and Presenter's Notes

Title: 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 Session Common 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 Session Common 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 Session Common 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 Session Common 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 Session Good 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 Session Good 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 Session Good 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 Session Good 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 Session Good 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
About PowerShow.com