writing better requirements

Writing Better RequirementsThe Key to a Successful Project

Kimberly RobertsKimberly Roberts

Senior Application EngineerSenior Application Engineerkimberly_kimberly_robertsroberts@@qssincqssinc.com.com

Copyright QSS, Inc. 1999

ObjectivesObjectives

ää Learn how good requirements definition canLearn how good requirements definition canbenefit your organization.benefit your organization.

ää Learn what the differences are betweenLearn what the differences are betweenUser Requirements, System RequirementsUser Requirements, System Requirementsand Architectural Design Requirementsand Architectural Design Requirements

ää Explore the anatomy of a requirement andExplore the anatomy of a requirement andcharacteristics of a good requirementcharacteristics of a good requirement


Why projects failWhy projects fail

ää Incomplete requirements - 13.1%Incomplete requirements - 13.1%

ää Lack of user involvement - 12.4%Lack of user involvement - 12.4%

ää Lack of resources - 10.6%Lack of resources - 10.6%

ää Unrealistic expectations - 9.9%Unrealistic expectations - 9.9%

ää Lack of executive support - 9.3%Lack of executive support - 9.3%

ää Changing reqs/specs - 8.7%Changing reqs/specs - 8.7%

ää Lack of planning - 8.1%Lack of planning - 8.1%

ää Didn’t need it any longer - 7.5%Didn’t need it any longer - 7.5%Sources: Standish GroupSources: Standish Group

Scientific AmericanScientific American


Why projects succeedWhy projects succeed

ää User involvement - 15.9%User involvement - 15.9%

ää Management support - 13.9%Management support - 13.9%

ää Clear statement of reqs - 13.0%Clear statement of reqs - 13.0%

ää Proper planning - 9.6%Proper planning - 9.6%

ää Realistic expectations - 8.2%Realistic expectations - 8.2%

ää Smaller milestones - 7.7%Smaller milestones - 7.7%

ää Competent staff - 7.2%Competent staff - 7.2%

ää Ownership - 5.3%Ownership - 5.3%Sources: Standish GroupSources: Standish Group

Scientific AmericanScientific American


And the question is…...And the question is…...

How do we make a project How do we make a project successful?successful?


Write Better Requirements….Write Better Requirements….

It’s a It’s a HIGH LEVERAGEHIGH LEVERAGE activity!! activity!!

Requirements allow you to Requirements allow you to IMPROVEIMPROVEQuality with Quality with LESSLESS effort. effort.


Requirements are how wecommunicateRequirements are how wecommunicate

DevelopersDevelopers

CustomerCustomer

UsersUsers ManufacturersManufacturers

DesignersDesigners

ManagementManagement


What are Requirements?(They are the “To-Do” List of the Project Team)

What are Requirements?(They are the “To-Do” List of the Project Team)

ää List of List of WHATWHAT the Users need the Users need

ää List of List of WHATWHAT the System must do to the System must do toSatisfy their needsSatisfy their needs

ää List of List of WHATWHAT components must be built components must be built

ää List of List of WHATWHAT each component must each component must DODO,,and and HOWHOW they will they will INTERACTINTERACT

Requirements define the qualityRequirements define the qualityof the systemof the system


When are Good RequirementsEssential?

When are Good RequirementsEssential?

ää If you are building anything intended for someone else’s useIf you are building anything intended for someone else’s use

ää If you are building systems that do more than one thingIf you are building systems that do more than one thing

ää If you are building anything that will be used more thanIf you are building anything that will be used more thanonceonce

ää If you are building something that interacts with otherIf you are building something that interacts with othersystemssystems

ää If you are building a system that requires a specified level ofIf you are building a system that requires a specified level ofperformanceperformance

ää If you are building anything that involves payment or otherIf you are building anything that involves payment or otherconsideration (in other words, a consideration (in other words, a contractcontract))

Good requirements can make a differenceGood requirements can make a difference


Requirements Ensure You Buildthe Right Project the Right WayRequirements Ensure You Buildthe Right Project the Right Way

ArchitecturalArchitecturaldesigndesign

SystemSystemrequirementsrequirements

UserUserrequirementsrequirements

ComponentComponentdevelopmentdevelopment

ComponentComponentteststests

IntegrationIntegrationteststests

SystemSystemteststests

AcceptanceAcceptanceteststests

Verification

Verification

Validation

DE

FINITIO

N

DE

FINITIO

NIN

TEG

RA

TIO

N

INTE

GR

ATI

ON

VA

LID

ATI

ON

VA

LID

ATI

ON


Basic Types of RequirementsBasic Types of Requirements

ä TYPES OF DOCUMENTS

ä User or Business NeedsRequirements

ä System or FunctionalRequirements

ä Architectural Designä “Element” Requirements

(Software & Hardware)ä Interface Definition

Requirements

ä TYPES OF REQUIREMENTS

ä FunctionalRequirements

ä Non-FunctionalRequirements

ä Constraints

ä Design Guidelines


Document DefinitionsDocument Definitions

ä System/Functional Requirementsä What the System will do from the builders Perspective

ä Component Requirementsä Design level list of all things that each component

must do. Any Programmer/Engineer can build onefrom this document

ä Interface Requirementsä Description of the Protocol and Physical Interface

between Components of the System

ä User/Business Needs Requirementsä What the System should do from the Users Perspective


Key Number 1 :Know where we are going.

Capture user requirements toCapture user requirements tounderstand what user problemsunderstand what user problems

your product will solve.your product will solve.

USER/BUSINESS NEEDSUSER/BUSINESS NEEDSREQUIREMENTSREQUIREMENTS


If we don’t know where we’regoing….

ää we never get there.we never get there.

ää we think we’re there but in reality we arewe think we’re there but in reality we arenot.not.

ää we finally get there but it takes a long timewe finally get there but it takes a long timeto arrive.to arrive.

We have the time to do it over and over again but we never have the time to do it right the

first time!


How do we know wherewe’re going?

The different types of users tell us!

Corporateexecutives

CustomerMarketing

Testers

End users

Maintainers


Good user requirements areessential!

Good user requirements areessential!

Without good user requirementsWithout good user requirementsthere is no clear direction forthere is no clear direction for

building a product….building a product….Product team members can headProduct team members can head

in different directions! in different directions!


User NeedsUser Needs

ää Generated by:Generated by:ää Business AnalysisBusiness Analysis

ää Generated From:Generated From:ää User RequestsUser Requests

ää Business RulesBusiness Rules View By:View By:

•• PriorityPriority

•• ImportanceImportance

•• AcceptableAcceptable

•• YouYou Choose Choose

CorpCorpBusinessBusiness

RulesRules

EndEndUserUser

RqmtsRqmts

RFPRFP

ContractContract


Where do User Needs Come From?Where do User Needs Come From?


Anatomy of a User RequirementAnatomy of a User Requirement

“The order entry clerk shall be able to complete ten“The order entry clerk shall be able to complete tencustomer orders in less than 2 hours”customer orders in less than 2 hours”

This requirement identifies a real user type and an end result.This requirement identifies a real user type and an end result.

It also defines the success criteria in measurable terms.It also defines the success criteria in measurable terms.

The challenge is to seek out the userThe challenge is to seek out the usertype, end result, and success measure intype, end result, and success measure in

every requirement.every requirement.


Key Number 2 :Know What We Are Doing

“What do WE need to know to“What do WE need to know tobuild this?”build this?”

SYSTEM/FUNCTIONALSYSTEM/FUNCTIONAL

REQUIREMENTSREQUIREMENTS


What Makes Up a System?What Makes Up a System?

ää Descriptive ElementsDescriptive Elements

ää Functional or BehavioralFunctional or BehavioralBreakdownBreakdown

ää PerformancePerformance

ää InterfacesInterfaces

ää Non-Functional RequirementsNon-Functional Requirements

ää Traceability to UserTraceability to UserRequirementsRequirements

Components of System Requirements:

Key requirementsKey requirements

in herein here

Use attributesUse attributes

The core of the systemThe core of the systemrequirements documentrequirements document

Often a large part of aOften a large part of adocument required fordocument required forcontent to “make sense”content to “make sense”


System Requirements DocumentSystem Requirements Document

ll Defines a model of the system to be built - not the systemDefines a model of the system to be built - not the system

ll Defines some mixture of functionality, behavior, performance, andDefines some mixture of functionality, behavior, performance, andsystems constraintssystems constraints

ll It’s a model, not a complete system definitionIt’s a model, not a complete system definition

ll Organized by functionality or logical layoutOrganized by functionality or logical layout

ll As implementation free as possibleAs implementation free as possible

ll Every statement verifiable, with level and nature of test as attributesEvery statement verifiable, with level and nature of test as attributes

ll Defines professional constraints -- e.g. from different disciplines,Defines professional constraints -- e.g. from different disciplines,working environment, induced environment, safety, etc.working environment, induced environment, safety, etc.

ll Owned by systems engineers, viewable to everyone includingOwned by systems engineers, viewable to everyone includingcustomers and designerscustomers and designers


Different Attributes BetweenUser and System RequirementsDifferent Attributes BetweenUser and System Requirements

ää Users are responsible for prioritizing a user requirementUsers are responsible for prioritizing a user requirement

ää Developers for costing the requirementDevelopers for costing the requirement

ää In the end, the user representative should decide whetherIn the end, the user representative should decide whethercost is worth the resultcost is worth the result

UserRequirements

Priority Cost

SystemRequirements

Implement?

User ResponsibilityUser Responsibility Developer ResponsibilityDeveloper Responsibility

High Yes MediumMedium Yes MediumHigh Yes LowLow No HighMedium No High


Key Number 3 :Know What to Build and Implement

Decomposition to detailedDecomposition to detaileddesign anddesign and

subsystem componentssubsystem components

ARCHITECTURALARCHITECTURALDESIGNDESIGN

REQUIREMENTSREQUIREMENTS


What Makes up the Design?What Makes up the Design?

ää Descriptive ElementsDescriptive Elements

ää Component Behavior/ControlComponent Behavior/Control

ää Component FunctionalityComponent Functionality

ää Component InterfacesComponent Interfaces

ää Component LayoutComponent Layout

ää Dependencies & ResourcesDependencies & Resources

ää Test CriteriaTest Criteria

ää Traceability to SystemTraceability to SystemRequirementsRequirements

Components of Architectural Design:

Key requirementsKey requirements

often in hereoften in here

Make use of attributesMake use of attributes

The core of the systemThe core of the systemcomponent designcomponent design

System or componentSystem or componentlevel constraintslevel constraints


Architectural Design DocumentArchitectural Design Document

ll Defines WHAT is to be built, how it behaves, how it is laid outDefines WHAT is to be built, how it behaves, how it is laid out

ll Defines key components, interfaces, control structures & externalDefines key components, interfaces, control structures & externalsystemssystems

ll Detailed enough for optimization, partitioning to contractors, andDetailed enough for optimization, partitioning to contractors, anddefinition of configuration item structuredefinition of configuration item structure

ll Basis for all milestonesBasis for all milestones

ll States what the system/component IS, not just its functionalityStates what the system/component IS, not just its functionality

ll Every statement verifiable and ready for integration tests withEvery statement verifiable and ready for integration tests withattributes to track states and methods of verificationattributes to track states and methods of verification

ll Created by designers, owned by developers, viewable by allCreated by designers, owned by developers, viewable by all

ll Cost estimation should be well definable at this stageCost estimation should be well definable at this stage


Design versus System LevelRequirementsDesign versus System LevelRequirements

SupplyPower

HeatCabin

System RequirementsSystem Requirements

Architectural DesignArchitectural Design

Gas DrivenGenerator

ElectricalHeater

FunctionalFunctionaldefinition of twodefinition of twofunctions andfunctions andan interfacean interface

10 kW10 kW

600 volts 18 Amp600 volts 18 Amp

400 Hertz400 Hertz

EquivalentEquivalentinterfaceinterface

definition indefinition indesign phasedesign phase


Key Number 4 :Take Command

The Anatomy of aThe Anatomy of aBetter Requirement…..Better Requirement…..

WRITE BETTERWRITE BETTERREQUIREMENTS!REQUIREMENTS!


Typical Requirement ProblemsTypical Requirement Problems

ää Inappropriate LevelInappropriate Level

ää Poor DefinitionPoor Definition

ää Lack of Structure and ControlLack of Structure and Control

ää Undefined OwnershipUndefined Ownership

ää No TraceabilityNo Traceability

ää No Completion CriteriaNo Completion Criteria


What is a Requirement?What is a Requirement?

ää Must form a complete sentence (not a bullet list ofMust form a complete sentence (not a bullet list ofbuzz words, list of acronyms, or “sound bites”)buzz words, list of acronyms, or “sound bites”)

ää States a subject and predicate where the subject is aStates a subject and predicate where the subject is auseruser

ää Consistent use of the “to be” verb:Consistent use of the “to be” verb:ää shallshall,, will will or or must must to show mandatory nature to show mandatory nature

ää shouldshould or or maymay to show optionality to show optionality

ää Has end resultHas end result

ää Contains success criteria or is testable in natureContains success criteria or is testable in nature


Types of RequirementsTypes of Requirements

ää Functional RequirementsFunctional Requirementsuu Capability that the system must performCapability that the system must perform

ää Non-Functional RequirementsNon-Functional Requirementsuu Conditions that must be met that are not explicitConditions that must be met that are not explicit

capabilities capabilities ((ieie: the system must run with 32M of RAM): the system must run with 32M of RAM)

ää Constraints/GuidelinesConstraints/Guidelines


Characteristics of GoodRequirementsCharacteristics of GoodRequirements

ää ClearClear Avoid confusionAvoid confusionää BriefBrief Short and simpleShort and simpleää VerifiableVerifiable Testable and verifiableTestable and verifiableää TraceableTraceable Uniquely identified and can be trackedUniquely identified and can be tracked

ää PriorityPriority Emphasize important requirementsEmphasize important requirements

ää SourceSource Who requires it?Who requires it?

ää UrgencyUrgency When?When?

ää IdentityIdentity Requirements must be uniquely identifiableRequirements must be uniquely identifiable

ää CommentsComments Clarification recorded when neededClarification recorded when needed

ää Query/ResponseQuery/Response All can benefit from discussionsAll can benefit from discussions

Each Individual Requirement Should Be:Each Individual Requirement Should Be:

Each Requirement Should Be Annotated with Attributes:Each Requirement Should Be Annotated with Attributes:


Characteristics of GoodDocumentsCharacteristics of GoodDocuments

ää CompleteComplete Are all requirements expressed?Are all requirements expressed?

ää BalancedBalanced Are requirements at a consistent level of detail?Are requirements at a consistent level of detail?

ää ModularModular Can system be changed without unforeseen side effects?Can system be changed without unforeseen side effects?

ää CorrectCorrect Are user needs correctly expressed?Are user needs correctly expressed?

ää ConsistentConsistent No contradictions exist between requirements?No contradictions exist between requirements?

ää RealisticRealistic Can we really build it?Can we really build it?

ää Role/State/ModeRole/State/Mode Are requirements associated with user roles/system states?Are requirements associated with user roles/system states?

ää Type InclusiveType Inclusive Functional, Non-Functional, Constraints, GuidelinesFunctional, Non-Functional, Constraints, Guidelines

Each Collection of Requirements Should Be:Each Collection of Requirements Should Be:


Traceability Ensures QualityTraceability Ensures Quality

Without traceability productscan drift away from what

the user requires

Requirements

“Quality is conformance“Quality is conformanceto requirements.to requirements.


Verifiability Ensures QualityVerifiability Ensures Quality

ää Track the Source and Status of yourTrack the Source and Status of yourRequirements with AttributesRequirements with Attributesää Record the source (when created, rationale, original text)Record the source (when created, rationale, original text)

ää Record urgency (mandatory, useful, optional, luxury)Record urgency (mandatory, useful, optional, luxury)

ää Record acceptance (proposed, reviewed, accepted, rejected)Record acceptance (proposed, reviewed, accepted, rejected)

ää Identify verification method (test, demonstration, inspection,Identify verification method (test, demonstration, inspection,simulation, analysis)simulation, analysis)

ää Identify constraints (safety, performance, reliability,Identify constraints (safety, performance, reliability,corporate standards, business rules)corporate standards, business rules)

ää Record discussion (comments, action items, proposedRecord discussion (comments, action items, proposedchange, state of review process)change, state of review process)


Analysis Now Made SimpleAnalysis Now Made Simple

Once this wealth of information is captured and well written,the status of a project can be easily determined:

Show all high priority requirements for the pilot on the flight controlsubsystem:

Priority = HighUser = PilotSubsystem = Flight Control

Show all the requirements maintenance users proposed that could effectsafety and performance:

User = MaintenanceStatus = ProposedConstraints = Safety & Performance


The keys to writing better requirementslead to successful projects!

User Requirements

BetterRequirements

SystemRequirements

ArchitecturalDesign

www.www.qssincqssinc.com.com