Writing effective requirements

71
Presented at a SA staff meeting at NCEN by Liz Lavaveshkul Source: TeleLogic

description

This slide show, which discusses characteristics of good user requirements, was presented during a systems analyst staff meeting at ncen.

Transcript of Writing effective requirements

Page 1: Writing effective requirements

Presented at a SA staff meeting at NCENby Liz Lavaveshkul

Source: TeleLogic

Page 2: Writing effective requirements

What is requirements management?

“The purpose of requirements management is to establish a common understanding between the customer and the … project … This agreement with the customer is the basis for planning and managing the … project.”

The Capability Maturity Model for Software (CMM) from the Software Engineering Institute at Carnegie Mellon University.

www.sei.cmu.edu/cmm

Page 3: Writing effective requirements

Why is RM so important?

Approximately 60 – 70% of projects failures result from poor requirements gathering, analysis, and management.

-- Mela Group, March 2003

Page 4: Writing effective requirements

Why bother with Requirements?• To show what results the users want• To communicate and focus team members

on clear goals• To tell decision-makers what is required

vs. desired• To allow the design to be optimized

Page 5: Writing effective requirements

Why bother with Requirements?• To supply confidence in the system

THOUGHOUT its development• To check that the system and all its parts

do what is wanted• To prevent over design or omitted needs• To control development and outsourcing

Page 6: Writing effective requirements

Why do you need requirements management?

• The status of the project is never clear until we find we’ve missed project milestones

• We have very little formal development process• The objectives always seem to change at the worst

times• Change is very costly and time consuming for us• We have difficulty communicating intent between

departments• We end up over-engineering our solutions, which is

costly

Do any of the following statements seem familiar?

Page 7: Writing effective requirements

Why do you need requirements management?

• We have trouble testing against original intent and stated need

• We are never sure whether our tests are full and complete

• Our test cycles are often too long and costly

• Our customers often include design in the requirements

• We have difficulty organizing requirements into smaller manageable sets

Page 8: Writing effective requirements

Who should use a RM tool?

• Systems Engineers demand functionality

• Highly advanced requirements management and analysis

• Distributed users demand collaboration

• Analyst/Architect demand a common language

• Reviewers demand instant access from any location

• Interested in central set of requirements accessed globally

• Need for multi-disciplines to communicate more efficiently

• Not so advanced, mainly interested in review functionality

Page 9: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction• Integration• Testability• Communication• Visibility• Change control• Quality• Optimization• Compliance

Page 10: Writing effective requirements

The Benefits of Requirements Management

• SatisfactionSatisfaction: real business needs met• Integration• Testability• Communication• Visibility• Change control• Quality• Optimization• Compliance

Page 11: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction: real business needs met

• IntegrationIntegration: the pieces work together• Testability• Communication• Visibility• Change control• Quality• Optimization• Compliance

Page 12: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction: real business needs met• Integration: the pieces work together

• TestabilityTestability: know what to test the delivery against• Communication• Visibility• Change control• Quality• Optimization• Compliance

Page 13: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction: real business needs met• Integration: the pieces work together• Testability: know what to test the delivery against

• CommunicationCommunication: consistent ideas of what the solution is for

• Visibility• Change control• Quality• Optimization• Compliance

Page 14: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction: real business needs met• Integration: the pieces work together• Testability: know what to test the delivery against• Communication: consistent ideas of what the solution is for

• VisibilityVisibility: managers can take a global view

• Change control• Quality• Optimization• Compliance

Page 15: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction: real business needs met• Integration: the pieces work together• Testability: know what to test the delivery against• Communication: consistent ideas of what the solution is for• Visibility: managers can take a global view

• Change controlChange control: the impact of change can be assessed

• Quality• Optimization• Compliance

Page 16: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction: real business needs met• Integration: the pieces work together• Testability: know what to test the delivery against• Communication: consistent ideas of what the solution is for• Visibility: managers can take a global view• Change control: the impact of change can be assessed

• QualityQuality: we know what quality means for the business

• Optimization• Compliance

Page 17: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction: real business needs met• Integration: the pieces work together• Testability: know what to test the delivery against• Communication: consistent ideas of what the solution is for• Visibility: managers can take a global view• Change control: the impact of change can be assessed• Quality: we know what quality means for the business

• OptimizationOptimization: we deliver only what is wanted• Compliance: demonstrate compliance with regulatory authorities and SOX

Page 18: Writing effective requirements

The Benefits of Requirements Management

• Satisfaction: real business needs met• Integration: the pieces work together• Testability: know what to test the delivery against• Communication: consistent ideas of what the solution is for• Visibility: managers can take a global view• Change control: the impact of change can be assessed• Quality: we know what quality means for the business• Optimization: we deliver only what is wanted

• ComplianceCompliance: demonstrate compliance with regulatory authorities and SOX

Page 19: Writing effective requirements

Types of Requirements• User Requirements – define

the results the users expect from the system

• System Requirements – define what the system must do to satisfy the users

• Design Requirements – define all of the components necessary to achieve the system requirements

“The homeowner shall hear an alarm when smoke is detected.”

“The alarm will produce a sound between 125 – 155 dBA.”

“The alarm will be produced by part # 123-45-678.”

Page 20: Writing effective requirements

Writing a requirement• Uses complete sentences• States subject and predicate

– Subject is a user type or the system under consideration– Predicate is a condition, action, or intended result

• Consistent use of language• Specifies:

– Desired goal or result (User requirement)– Function (System requirement)– Constraint (either)

• Contains a success criterion or other measurable indication of the quality

Page 21: Writing effective requirements

Language• Use consistent language, for example:

– “Shall,” “will,” or “must” are mandatory– “Should” is optional, but omission must be justified– “May” is desirable

• Use consistent terminology– Define terms – use a Glossary– Avoid using the same name for different things– Avoid using different names for the same thing

Page 22: Writing effective requirements

Anatomy of a Good User Requirement

“The Internet user shall be able to access their current account balance in less than 5 seconds.”

Defines a user type

Defines a positive end result

“To be” verb

Performance criteria

Page 23: Writing effective requirements

Anatomy of a Good User Requirement

• This requirement sentence identifies a specific user and end result that is wanted within a specified time.

“The Internet user shall be able to access their current account balance in less than 5 seconds.”

Defines a user type “To be” verb

Defines a positive end result Performance criteria

The challenge is to seek out the user type, end result, and success measure in every requirement you define.

Page 24: Writing effective requirements

Anatomy of a Good User Requirement

• It also defines the success in measurable terms: “access … account balance in less than 5 seconds.”

“The Internet user shall be able to access their current account balance in less than 5 seconds.”

Defines a user type “To be” verb

Defines a positive end result Performance criteria

The challenge is to seek out the user type, end result, and success measure in every requirement you define.

Page 25: Writing effective requirements

Characteristics of a Good Requirement

• Correct

• Complete

• Clear

• Consistent

• Verifiable

• Traceable• Feasible• Modular• Design-Free• Positive

Page 26: Writing effective requirements

Characteristics of a Good Requirement

• Correct

• Complete

• Clear

• Consistent

• Verifiable

Technically and legally possible

Page 27: Writing effective requirements

Characteristics of a Good Requirement

• Correct

• Complete

• Clear

• Consistent

• Verifiable

Technically and legally possible

Expresses a whole idea or statement

Page 28: Writing effective requirements

Characteristics of a Good Requirement

• Correct

• Complete

• Clear

• Consistent

• Verifiable

Technically and legally possible

Unambiguous and not confusing

Expresses a whole idea or statement

Page 29: Writing effective requirements

Characteristics of a Good Requirement

• Correct

• Complete

• Clear

• Consistent

• Verifiable

Technically and legally possible

Unambiguous and not confusing

Expresses a whole idea or statement

Not in conflict with other requirements

Page 30: Writing effective requirements

Characteristics of a Good Requirement

• Correct

• Complete

• Clear

• Consistent

• Verifiable

Technically and legally possible

Unambiguous and not confusing

Expresses a whole idea or statement

Not in conflict with other requirements

It can be determined that the system meets the requirement

Page 31: Writing effective requirements

Characteristics of a Good Requirement

• Traceable• Feasible• Modular• Design-Free• Positive

Uniquely identified and can be tracked

Page 32: Writing effective requirements

Characteristics of a Good Requirement

• Traceable• Feasible• Modular• Design-Free• Positive

Uniquely identified and can be tracked

Can be accomplished within cost & schedule

Page 33: Writing effective requirements

Characteristics of a Good Requirement

• Traceable• Feasible• Modular• Design-Free• Positive

Uniquely identified and can be tracked

Can be changed without excessive impact

Can be accomplished within cost & schedule

Page 34: Writing effective requirements

Characteristics of a Good Requirement

• Traceable• Feasible• Modular• Design-Free• Positive

Uniquely identified and can be tracked

Can be changed without excessive impact

Can be accomplished within cost & schedule

Does not impose specific solution on design (i.e., implementation free)

Page 35: Writing effective requirements

Characteristics of a Good Requirement

• Traceable• Feasible• Modular• Design-Free• Positive

Uniquely identified and can be tracked

Can be changed without excessive impact

Can be accomplished within cost & schedule

Does not impose specific solution on design (i.e., implementation free)

Written in the affirmative, not the negative

Page 36: Writing effective requirements

Requirements Should be Correct• The requirement should be technically and

legally achievable– Have studies been completed?– Does the technology exist?– Will the implementation of the requirement stay within

existing legal guidelines?

Page 37: Writing effective requirements

Requirements Should be Correct

A correct requirement is one which does not try to achieve some “pie in the sky” objective.

For example, the requirement “The system shall be 100% reliable” is technically not achievable.

Page 38: Writing effective requirements

Requirements Should be Correct

A requirement may be technically achievable, but not necessarily legally feasible because it may be outside the framework of existing legal regulations.

For example, allowing the user to access private information online, without the necessary security checking, is technically achievable, but is contrary to current federal regulations.

Page 39: Writing effective requirements

Requirements Should be Complete• Express a whole idea or statement

– Is the requirement standalone?– Is the requirement dependent on preceding

requirements at that level of achievement?– Is the requirement necessary for subsequent

requirements at that level of development?

Page 40: Writing effective requirements

Requirements Should be Complete

A complete requirement should not depend on other requirements to be implemented. If a requirement states “The radar system shall track aircraft,” it leaves the reader asking “How many? Inbound or outbound?”

Page 41: Writing effective requirements

Requirements Should be Complete

Also, beware of multiple requirements contained within a single statement. For example, “The system shall determine the number of users online at all times and pass the number of users to the system administrator who shall have the ability to disconnect users from the Internet.”

Page 42: Writing effective requirements

Requirements Should be Complete

Instead, the statement can be broken down into atomic statements:

Beware of multiple requirements contained within a single statement. For example, “The system shall determine the number of users online at all times and pass the number of users to the system administrator who shall have the ability to disconnect users from the Internet.”

“The system shall maintain a log of online users.”“The system shall provide log information to the system administrator.”“The system shall allow the system administrator to disconnect user(s) from the network.”

Page 43: Writing effective requirements

Requirements Should be Clear• The requirement should be unambiguous

and not confusing– Use words that are not confusing– Use a commonly agreed set of terms– The construct of the sentence should be standard– Use definite, concrete terms– Omit needless words– Avoid language the target reader may not understand– Do not overwrite

Page 44: Writing effective requirements

Requirements Should be Clear

When writing a requirement, always strive to maintain clarity. An excellent reference is “The Elements of Style” by Strunk and White.

For example, don’t “utilize” a function, rather “use” a function.

Page 45: Writing effective requirements

Requirements Should be Clear

When you use the word “system,” do all the readers have the same understanding of the word?

If you try to impress your readers with arcane grammar only used in graduate-level English classes, you will most likely confuse and irritate them, as they will have to reach for the dictionary too many times.

Page 46: Writing effective requirements

Requirement Should be Consistent• The requirement should not be in conflict

with other requirements– Are there redundancies?– Are the same terms used throughout?– Are all requirements referencing the same dictionary?– Requirements repeated in many sections can be

pulled into a common requirements set to avoid duplication

Page 47: Writing effective requirements

Requirements Should be Verifiable• Verification Methods:

– TestingTesting

– AnalysisAnalysis

– DemonstrationDemonstration

– InspectionInspection

Page 48: Writing effective requirements

Requirements Should be Verifiable• It can be determined that the system

meets the requirement using one of the standard verification methods:

• TestingTesting: Usually the most comprehensive of the verification methods. This is also commonly referred to as “white box” testing. This method tests not only the output, but also how the output is achieved, considering the unique internal deviations as a result of different states and nodes.

Page 49: Writing effective requirements

Requirements Should be Verifiable

• AnalysisAnalysis: This method generally uses mathematical algorithms (expressed nowadays in computer simulations) to ensure the requirement is met.

Page 50: Writing effective requirements

Requirements Should be Verifiable

• DemonstrationDemonstration: also known as “black box” testing, where the system is given input, and the output is compared against the expected results.

Page 51: Writing effective requirements

Requirements Should be Verifiable

• InspectionInspection: As the name implies, this method checks or inspects the system to ensure conformity to the requirement.

Page 52: Writing effective requirements

Requirements Should be Verifiable• You should always ask, “Is the

requirement testable?” • When the requirement is implemented and

the system is built, you need to verify that the system, indeed, does what is required of it.– To verify the system, people generally use

one of the four classic verification methods mentioned previously. (Testing, Analysis, Demonstration, and Inspection)

Page 53: Writing effective requirements

Requirements Should be Traceable• The requirement should have a unique

identifier and traced to its origin.– Ensures completeness– Prevents “scope creep”– It is a specific goal in any Requirements Management

process– Allows quick impact assessment when requirements

change

Page 54: Writing effective requirements

Requirements Should be Traceable• A primary aim of any requirements

management process is traceability of requirements. How much traceability?100%!

Page 55: Writing effective requirements

Requirements Should be Traceable• According to Standish Group, 52% of

required functionality is never included in the finished system. Then, when system testing commences, you discover the missing functionality. You then have to not only fix the system to accommodate the missing functionality, but you have to test all of the other requirements again to ensure that the fixed requirement will not break any existing functions (commonly referred to as regression)

Page 56: Writing effective requirements

Requirements Should be Traceable• When requirements change, as they

almost always do, the impact must be accessed to ensure that the potential change will still satisfy the parent requirements and not adversely impact the child requirements.

Page 57: Writing effective requirements

Requirements Should be Feasible• The requirement should be written so as to

be achievable within cost and schedule– Do you have the resources?– Do you have the time?– Do you have the right people?

Page 58: Writing effective requirements

Requirements Should be Feasible

A requirement may be technically achievable, but way beyond the scope of current project resources.

For example, you have a requirement that states, “The system shall maintain a 99.9% mean time between failures,” but the costs of achieving 99.9% reliability may be so exorbitant that the other requirements may not be implemented due to insufficient resources.

Page 59: Writing effective requirements

Requirements Should be Modular• The requirement should have limited

cross-referencing interdependency.– Group similar requirements together– The use of a standardized outline structure helps

tremendously with achieving modularity.

Page 60: Writing effective requirements

Requirements Should be Modular

This allows the requirement to be changed without excessive impact. For example, the I.E.E.E. 12207 standard contains the different outline templates for the various types of requirements in a system, from the Concept of Operations (CONOPS) to the Software Test Plan (STP).

Page 61: Writing effective requirements

Requirements Should be Modular• When you use these templates, you

achieve several goals:– You start achieving modularity– You are starting to standardize your process

Page 62: Writing effective requirements

Requirements Should be Design-Free

• The requirement should be implementation-free– Avoid design– Describe what is required, not how it would be

implemented– The requirement should be written with enough detail

to satisfy the level above– The requirement should be written at a level of

abstraction to be design free for the next level below

Page 63: Writing effective requirements

Requirements Should be Design-Free• During requirements development, we tend to want to

jump right into the design of the system• Instead of trying to describe the desired functionality or

stakeholder wants, we tend rather to state how the system will be implemented. Many times, this leads to increased cost and complexity because the optimal design space has now been restricted.

• For example, a system requirements document may state: “The network shall use an ATM protocol.” This constrains the design of the network to use ATM technology, when another protocol may be the more cost effective solution.

Page 64: Writing effective requirements

Requirements Should be Positive• Requirements should be written in the

affirmative. – Reduces the chances of having two requirements say

the same thing.– Reduces the possibility of two requirements being

inconsistent — one stating something in the affirmative and one in the negative but with different conditions or numeric values

– Helps with the verification — it is much easier to test to a positive statement where something observable will happen as a result of a user action

Page 65: Writing effective requirements

Requirements Should be Positive

– A negative statement that a user action or statement that something will not result in a condition would be more difficult to test and observe

– Less chance of misinterpretation, especially in the case of double or multiple negatives

Page 66: Writing effective requirements

Requirements Should be Positive

For instance, instead of stating:

“No unsuccessful login attempts will go unrecorded.”

Try rather:

“All unsuccessful login attempts shall be recorded.”

Page 67: Writing effective requirements

Quiz Time!

Page 68: Writing effective requirements

Rate this Requirement

“The Order Entry system provides for quick, user-friendly and efficient entry and processing of all orders.”

Is this a good requirement? If not, recommend an improvement.

Page 69: Writing effective requirements

Rate this Requirement

“Invoices, acknowledgements, and shipping notices shall be automatically faxed during the night, so customers can get them first thing in the morning.”

Is this a good requirement? If not, recommend an improvement.

Page 70: Writing effective requirements

Rate this Requirement

“The system OS shall be upgraded in one whack.”

Is this a good requirement? If not, recommend an improvement.

Page 71: Writing effective requirements

Rate this Requirement

“The ATM user shall be able to view the current account balance after an update within 5 seconds.”

Is this a good requirement? If not, recommend an improvement.