Object-Oriented Object-Oriented Software EngineeringSoftware Engineering

Writing RequirementsWriting Requirements

Paul J KrausePaul J Krause

CreditsCredits

Most of this material has been reused from Most of this material has been reused from slides presented by Tom and Kai Gilb slides presented by Tom and Kai Gilb (with permission)(with permission)

See:See:

http//:www.gilb.comhttp//:www.gilb.com

Why Requirements?Why Requirements?“The firms improving their development speed at the fastest rate actually spend more elapsed time and more effort in the customer requirements stage of the project …. These firms spend significantly less time in the testing and integration stage of development.…”

“The firms improving their development speed at the fastest rate actually spend more elapsed time and more effort in the customer requirements stage of the project …. These firms spend significantly less time in the testing and integration stage of development.…”

Blackburn, Scudder, et al, in Improving Speed and Productivity of Software Development: A Global Survey of Software Developers (1996)

0%

5%

10%

15%

20%

Schedule Effort

Faster FirmsSlower Firms

Resources spent on Customer Requirements:

Planguage advances and differences over Planguage advances and differences over conventional requirements specificationconventional requirements specification

Below are given some IEEE definitions of ‘Requirement’Below are given some IEEE definitions of ‘Requirement’

Requirement: Requirement: a condition or capability needed a condition or capability needed

by a user to solve a problem or by a user to solve a problem or achieve an objective. achieve an objective. <- [IEEE 610.12-1990]<- [IEEE 610.12-1990]

Example of an IEEE definition of Example of an IEEE definition of ‘requirement’. The term ‘user’ is ‘requirement’. The term ‘user’ is probably not broad enough to probably not broad enough to capture the scope of all capture the scope of all stakeholders.stakeholders.

Does not distinguish well Does not distinguish well enough from means/designenough from means/design

Requirements:• Statements, which identify the essential needs for a system in order for it to have value and utility. •Requirements may be derived or based upon interpretation of stated requirements to assist in providing a common understanding of the desired operational characteristics of a system.

<- IEEE P1220. IEEE Standard for Systems Engineering, Preliminary, 1993 in [SEI-95-MM-003]

Tom on ‘Requirement’Tom on ‘Requirement’ Requirement: Requirement: Concept *026 November 8, 2001 22:16Concept *026 November 8, 2001 22:16

A requirement is a stakeholder-desired A requirement is a stakeholder-desired Target or Constraint.Target or Constraint.

Notes: Notes: 1. The constraints can apply to an engineering process, a design or an 1. The constraints can apply to an engineering process, a design or an

operational system.operational system. 2. A requirement is an input to a defined level of design process. 2. A requirement is an input to a defined level of design process. 3. Requirements give information to the designer about the necessary 3. Requirements give information to the designer about the necessary

nature of their design. nature of their design. 4. Consequently the design, specification or implementation, can be 4. Consequently the design, specification or implementation, can be

judged {Spec QC, review, test or in operation} in terms of how well it judged {Spec QC, review, test or in operation} in terms of how well it satisfies those requirements.satisfies those requirements.

INTRO

Requirement Specification.Requirement Specification. Requirement Specification. Concept *508. November 8, Requirement Specification. Concept *508. November 8,

2001 16042001 1604

A requirement specification is the A requirement specification is the readable expression of a readable expression of a requirement and any requirement requirement and any requirement background.background.

Related Concepts: Related Concepts: requirement *026 the future state or constraintrequirement *026 the future state or constraint specification *137 the readable specification *137 the readable artifactartifact background *507 additional information about the requirementbackground *507 additional information about the requirement

Analysis of dangerous common Analysis of dangerous common requirements practices.requirements practices.

Mixing real requirements with ‘designs’Mixing real requirements with ‘designs’ Failing to quantify competitive qualitiesFailing to quantify competitive qualities Failing to derive implied requirements from designsFailing to derive implied requirements from designs Failing to set requirements at appropriate levelFailing to set requirements at appropriate level Failing to include source informationFailing to include source information Failing to include priority informationFailing to include priority information Failing to specify all critical stakeholders requirementsFailing to specify all critical stakeholders requirements Failing to distinguish between wishes and their profitFailing to distinguish between wishes and their profit Failing to consider all limited resources as requirementsFailing to consider all limited resources as requirements Failure to update requirements evolutionarilyFailure to update requirements evolutionarily Failure to consider time, location and conditions with requirementsFailure to consider time, location and conditions with requirements Failure to plan a time series of quality levelsFailure to plan a time series of quality levels

Planguage focus: Ends over meansPlanguage focus: Ends over means Deming on true aimsDeming on true aims

““The aim must include plans for the future” The aim must include plans for the future” <- <- [DEMING93, page 51][DEMING93, page 51]

““It is important that an aim never be defined in It is important that an aim never be defined in terms of terms of activity or methodsactivity or methods. It must always relate . It must always relate to how life is better for everyone.” to how life is better for everyone.” <-[DEMING93, page <-[DEMING93, page 52]52]

““<- [DEMING93, page 52] Attributed to Deming by <- [DEMING93, page 52] Attributed to Deming by The aim The aim precedes the organizational system and those precedes the organizational system and those that work in it. Workers, for example, can not be that work in it. Workers, for example, can not be the source of the aim, for how would one know the source of the aim, for how would one know what kind of workers to choose?” what kind of workers to choose?” Carolyn BaileyCarolyn Bailey

QuickTime™ and aPlanar RGB decompressor

are needed to see this picture.

Planguage is about ‘Clarity’Planguage is about ‘Clarity’

““For me, a For me, a hypothesis is hypothesis is

a statement whose a statement whose truthtruth is temporarily is temporarily assumed, assumed,

but whose but whose meaningmeaning must be must be beyond all doubtbeyond all doubt.”.”

Source: Calaprice p 235 see slide note for detail

E = mc2 + … 1912 Special Theory of Relativity. (source data in slide note)

Stakeholders: requirements Stakeholders: requirements sourcessources

‘‘Stakeholders’ are:Stakeholders’ are: Any person, group or thing whichAny person, group or thing which

• Can determine our system’s degree of success or failureCan determine our system’s degree of success or failure• By having an “opinion” aboutBy having an “opinion” about

system performance characteristicssystem performance characteristics system lifecycle constraintssystem lifecycle constraints

Stakeholders determine requirements!Stakeholders determine requirements! Systems engineers determine which requirements the Systems engineers determine which requirements the

stakeholders needstakeholders need• Even if the stakeholders are not currently conscious of those Even if the stakeholders are not currently conscious of those

needs!needs!

Stakeholder: Concept *233 .Stakeholder: Concept *233 .

‘‘Stakeholders’ are: Stakeholders’ are: Any person, group or thing Any person, group or thing

that can determine our systems degree of that can determine our systems degree of success or failure, success or failure,

by having an opinion aboutby having an opinion about

  system performance characteristics and system performance characteristics and

system lifecycle constraints system lifecycle constraints

Stakeholder InterestsStakeholder Interests

For example they might have an interest inFor example they might have an interest in1.1. Setting the objectives for a process.Setting the objectives for a process.2.2. Evaluating the quality of the productEvaluating the quality of the product3.3. Using the product or system, even indirectlyUsing the product or system, even indirectly4.4. Avoiding problems for themselves as a Avoiding problems for themselves as a

result of our product or system.result of our product or system.• Being compatible with another machine or software Being compatible with another machine or software

component.component.• Determining constraints on development, operation or Determining constraints on development, operation or

retirement of the system.retirement of the system.

Performance Requirements: Qualities, Performance Requirements: Qualities, Quantities, SavingsQuantities, Savings

Constraints: Limits and FencesConstraints: Limits and Fences

O-----<=====>------>O-----<=====>------>Levels-of-performance conceptsLevels-of-performance concepts

Performance-related concepts Performance-related concepts Target view O------Target view O------>>------->------->

•The future-state requirement level >The future-state requirement level >Value O----Value O---->>---->---->

•Same as Target, but implies a stakeholder exists Same as Target, but implies a stakeholder exists who ‘values’ that level.who ‘values’ that level.

Benchmarks O-------Benchmarks O-------<<-------->-------->•One or more fact-based reference levels to One or more fact-based reference levels to compare targets with, and ascertain valuecompare targets with, and ascertain value

Change view O----<Change view O----<========>--->>--->•The difference, or gap, between benchmarks and The difference, or gap, between benchmarks and targets represents planned change. targets represents planned change. •Normally this represents a planned degree of Normally this represents a planned degree of ‘improvement’ ‘improvement’

(but it can be any state, +, 0 and -).(but it can be any state, +, 0 and -).

Performance attributes Performance attributes can be viewed as:can be viewed as:

Quantities (= Capacities)Quantities (= Capacities) Like Like {Space, Time, {Space, Time,

Money, Effort, Data}” Money, Effort, Data}” How How MUCH?MUCH?

QualitiesQualities ‘‘How well’How well’ something is something is

done; “-ilities”done; “-ilities” Savings/Benefits/Savings/Benefits/

ImprovementsImprovements A Quantity or Quality A Quantity or Quality

which is better than some which is better than some defined benchmark defined benchmark alternative.alternative.

Performance.Capacity Model *459 Performance.Capacity Model *459 Sept.5 2001Sept.5 2001

SystemMission

Qualities (How well)

Savings(How much resource saved)

Capacities(How Much)

Resources

Performance Attributes

Work CapacityResponsiveness

Storage Capacity

Income

Data

Constraints: Binary and Constraints: Binary and ScalarScalar

Constraint: (Concept *218) September 7, 2001 Constraint: (Concept *218) September 7, 2001

A constraint is a requirement specification that A constraint is a requirement specification that explicitlyexplicitly and and intentionallyintentionally restricts the engineering process, a restricts the engineering process, a systems operation, or its lifecycle. systems operation, or its lifecycle.

There are two types of constraints: Binary and Scalar.There are two types of constraints: Binary and Scalar.

0:1 Binary Constraints are statements like ‘must/must not’. 0:1 Binary Constraints are statements like ‘must/must not’. These are called Demands (must) and Vetoes (must not).These are called Demands (must) and Vetoes (must not).

-|-|- Scalar Constraints are specified using a Scale of measure, -|-|- Scalar Constraints are specified using a Scale of measure, to limit some resource or capability in some way.to limit some resource or capability in some way.

StakeholdersStakeholders

Why you have to identify them formallyWhy you have to identify them formally How to find out and confirm their How to find out and confirm their

requirementsrequirements Example of classes of stakeholdersExample of classes of stakeholders How to specify stakeholders together with How to specify stakeholders together with

their requirements.their requirements.

Stakeholders:Stakeholders:Why you have to identify them formallyWhy you have to identify them formally

Stakeholders determine requirements!Stakeholders determine requirements! If you don’t identify all ‘critical’ stakeholdersIf you don’t identify all ‘critical’ stakeholders

You probably cannot identify all critical requirementsYou probably cannot identify all critical requirements If you don’t identify all critical requirementsIf you don’t identify all critical requirements

You will get delays and problems and failures sooner You will get delays and problems and failures sooner or lateror later

? IF WE HAVE GOT THE REQUIREMENT DO WE ? IF WE HAVE GOT THE REQUIREMENT DO WE THEN STILL NEED TO DOCUMENT THE THEN STILL NEED TO DOCUMENT THE STAKEHOLDERS CONCERNED?STAKEHOLDERS CONCERNED?

Stakeholders: Stakeholders: How to find out and confirm their How to find out and confirm their

requirementsrequirements

1. Identify all critical and profitable STAKE-HOLDERS

2. Identify All critical and profitable stakeholder REQUIRE-MENTS

3. Detail and clarify requirements (Scale +Benchmarks+Targets)

4. Validate and agree these requirements with stakeholders

5. Select most profitable requirements to deliver first (Evolutionary delivery)

6. Learn new requirements evolutionarily as result of experience feedback and time (new technology, markets and cost levels)

Stakeholders: Stakeholders: Example of classesExample of classes of of stakeholders;stakeholders;

Stakeholders: Stakeholders: How to specify stakeholders How to specify stakeholders together with their requirementstogether with their requirements..

The Planguage parameter term ‘The Planguage parameter term ‘Stakeholder’Stakeholder’ can be used to specify can be used to specify one or more stakeholders explicitly. one or more stakeholders explicitly.

Internal Interests: Stakeholder = {End User, Help Desk, Installer}Internal Interests: Stakeholder = {End User, Help Desk, Installer} We can attach stakeholder information to any elementary We can attach stakeholder information to any elementary

specification, specification, Usability: Scale: Time to learn a task for a defined [Stakeholder]Usability: Scale: Time to learn a task for a defined [Stakeholder] Goal [Stakeholder = Goal [Stakeholder = Novice UserNovice User] 10 minutes.] 10 minutes. Novice UserNovice User: Defined As: anyone without any training in this : Defined As: anyone without any training in this

system or task.system or task. or to a or to a setset of specifications, of specifications,

Scale [Installers] time for successful installationScale [Installers] time for successful installation Fail 20 minutes, Goal 10 minutes, Wish 5 minutes.Fail 20 minutes, Goal 10 minutes, Wish 5 minutes.

as appropriate.as appropriate.

??

Past: any useful reference point. Your old product, a competitors organization, or a quality achieved in same discipline but different branch of business.

Record: best in some class, state of the art. Something to beat. A challenge for you. An extreme Past.

Trend: a future guess based on Past.

Benchmarks:

PlanGUAGE

?

Fail do: a level constraint needed for avoiding some pain, loss, discomfort

Goal: the target level needed for satisfaction, happiness, joy and 100% full payment!

Wish: a target level desired by someone, but which might not be feasible. Project is not committed to it.

Requirements (Targets & Constraints)

Stretch: a motivational target, but a difficult target+

Survival: an extremely strong constraint level: Failure point

[ ]

3.3. Requirements Specification Rules;Requirements Specification Rules;DefinitionDefinition

RuleRule: : Concept *129. Concept *129. September 3 2001 September 3 2001

A rule is an engineering work process A rule is an engineering work process standard forstandard for specification specification writingwriting. .

A rule should be a significant highly-A rule should be a significant highly-recommended best practice. recommended best practice.

Failing to follow a specification rule should Failing to follow a specification rule should arguably threaten system economics or product arguably threaten system economics or product quality, quality,

and rule violation is therefore classified as and rule violation is therefore classified as a a ‘defect’‘defect’ in the specification. in the specification.

3. Requirements Specification Rules;3. Requirements Specification Rules;Example, Example, Part 1 of 7Part 1 of 7

GEN.1 (Consistency)GEN.1 (Consistency) Specifications must be consistent with all other Specifications must be consistent with all other

related specifications in the same document, and in related specifications in the same document, and in all related documents {Sources, Kin and Children}.all related documents {Sources, Kin and Children}.

GEN.2 (Unambiguous)GEN.2 (Unambiguous) All specifications must be unambiguous to the All specifications must be unambiguous to the

Intended Readership, as practiced or implied, for that Intended Readership, as practiced or implied, for that document.document.

3.3. Requirements Specification Rules;Requirements Specification Rules;Example, Example, Part 2 of 7Part 2 of 7

GEN.3 (Notes)GEN.3 (Notes) All manner of comment, notes, suggestion or ideas All manner of comment, notes, suggestion or ideas

which are not themselves the actual engineering which are not themselves the actual engineering specification, but merely background, shall be clearly specification, but merely background, shall be clearly distinguished as such by suitable devices.distinguished as such by suitable devices.

Suggested Devices: italics, ”double quotes”, Note:…, Suggested Devices: italics, ”double quotes”, Note:…, Comment:…., use of footnotes, use of separate commentary Comment:…., use of footnotes, use of separate commentary pages.pages.

GEN.4 (Brevity)GEN.4 (Brevity) All specification shall be as brief as possible, in order All specification shall be as brief as possible, in order

to successfully support their purpose, for the defined to successfully support their purpose, for the defined Intended Readership.Intended Readership.

3. Requirements Specification Rules;3. Requirements Specification Rules;Example, Example, Part 3 of 7Part 3 of 7

GEN.5 (Clarity of Purpose)GEN.5 (Clarity of Purpose) All specification shall result in All specification shall result in clarity to the Intended Readerclarity to the Intended Reader

regarding it’s regarding it’s purpose or intentpurpose or intent.. Note: it is not enough that the statements are unambiguous. They Note: it is not enough that the statements are unambiguous. They

must contain clarity of purpose: why is this here? must contain clarity of purpose: why is this here? “Clear enough “Clear enough to test”to test”

GEN.6 (Elementary)GEN.6 (Elementary) Specification statements shall be Specification statements shall be broken up into their most broken up into their most

elementaryelementary form. form. Note: this is so that they each can be unambiguously cross-referenced Note: this is so that they each can be unambiguously cross-referenced

externally.externally. Note: an elementary specification can be referred to by its tag (or Note: an elementary specification can be referred to by its tag (or

global tag), and within that, any unique combination of Parameter (for global tag), and within that, any unique combination of Parameter (for example Meter, Past) and/or Qualified (for example ”[UK, 1999]” ) example Meter, Past) and/or Qualified (for example ”[UK, 1999]” ) may be used to refer to or distinguish an elementary idea.may be used to refer to or distinguish an elementary idea.

3.3. Requirements Specification Rules;Requirements Specification Rules;Example, Example, Part 4 of 7Part 4 of 7

GEN.7 (Unique)GEN.7 (Unique) Specifications shall only have a Specifications shall only have a single instancesingle instance in the entire in the entire

project documentation.project documentation.

GEN.8 (ID Tags)GEN.8 (ID Tags) All specifications statements must have some unique and All specifications statements must have some unique and

unambiguous unambiguous cross-reference capabilitycross-reference capability, which is stable , which is stable (independent of sequence and changes).(independent of sequence and changes).

Statements may be directly tagged.Statements may be directly tagged. Statements may be referenced by a hierarchy of tagsStatements may be referenced by a hierarchy of tags Statements may be referenced in detail using Parameter names (like Statements may be referenced in detail using Parameter names (like

Meter, Goal) and Qualified (like [Euro, 2001])Meter, Goal) and Qualified (like [Euro, 2001]) References may have defined synonyms for convenience.References may have defined synonyms for convenience.

3. Requirements Specification Rules;3. Requirements Specification Rules;Example, Example, Part 5 of 7Part 5 of 7

GEN.9 (Reuse)GEN.9 (Reuse) Tagged Ideas shall be ’reused’ by cross-reference to Tagged Ideas shall be ’reused’ by cross-reference to

their unique tag, or their tag and version information.their unique tag, or their tag and version information.

GEN.10 (Source)GEN.10 (Source) Specifications shall contain detailed (paragraph, Specifications shall contain detailed (paragraph,

unique tag level) references about their exact and unique tag level) references about their exact and detailed sources.detailed sources.

Note use: ’Spec <- Source’ format or ’Source:……’Note use: ’Spec <- Source’ format or ’Source:……’

3. Requirements Specification Rules;3. Requirements Specification Rules;Example, Example, Part 6 of 7Part 6 of 7

GEN.11 (Hierarchy)GEN.11 (Hierarchy) Specifications shall be logically organized into a useful Specifications shall be logically organized into a useful

hierarchical structure.hierarchical structure. The tagging system shall reflect that structure (example A.B.C)The tagging system shall reflect that structure (example A.B.C)

Note: this may be partly done through templates.Note: this may be partly done through templates.

GEN.12 (Auditability)GEN.12 (Auditability) All changes to specifications shall be done in such a way as to All changes to specifications shall be done in such a way as to

permit us to know who changed things, what the previous permit us to know who changed things, what the previous version was, perhaps even justification for the change.version was, perhaps even justification for the change.

GEN.13 (Risk)GEN.13 (Risk) The specification Author must clearly indicate any information The specification Author must clearly indicate any information

which is uncertain or poses any risk to the project whatsoever, which is uncertain or poses any risk to the project whatsoever, using a variety of available devices such as {<fuzzy using a variety of available devices such as {<fuzzy brackets>, ??, ?, ranges (60->70, 60±10%), suitable comments brackets>, ??, ?, ranges (60->70, 60±10%), suitable comments or notes}.or notes}.

3. Requirements Specification Rules;3. Requirements Specification Rules;Example, Example, Part 7 of 7Part 7 of 7

GEN.14 (Template)GEN.14 (Template) The relevant electronic template shall be used, for The relevant electronic template shall be used, for

specific headings and guidance under each heading.specific headings and guidance under each heading.

GEN.15 (Model)GEN.15 (Model) A ’best practice’ model shall be defined and available. A ’best practice’ model shall be defined and available.

It shall be used to help interpret the intent of these It shall be used to help interpret the intent of these rules in practice.rules in practice.

Note: see extensive separate comments for justification of Note: see extensive separate comments for justification of these Rules, tag C.GENthese Rules, tag C.GEN