DOCUMENTING REQUIREMENTS

How do we document what the SW should do?

Lecture 7

Some slides in this lecture adapted from https://www.ifi.uzh.ch/en/rerg/courses/hs23/re-i.html

Announcements

• HW3 due tonight 11:59pm
• HW3 peer eval (optional) closes Thursday 11:59pm
• Mid-quarter evaluative feedback survey due Friday 11:59pm

Text questions to (562) 684-8307

2

Canvas Quiz

​

​

​

Lecture 7: Lecture 6 Review

Text questions to (562) 684-8307

3

Last Time – How do we figure out what the SW should do?

• Requirements come from stakeholders, documents, existing systems, context, goals, and observations
• Elicitation practices include asking, collaborating, building/playing, observing, and analyzing
• Structure elicited information into documents through analysis
• Collaborate with stakeholders to innovate
• Stakeholders may have conflicting requirements
• Negotiation needed

Text questions to (562) 684-8307

4

​

​

How do we document what the software should do?

Text questions to (562) 684-8307

5

Pre-work: How will you document?

• Written specifications
• Organized by feature
• Diagrams
• Use case
• Flow charts
• Categorize requirements
• Functional
• Non-functional
• Constraints
• User stories
• Tables
• Google docs
• Validate documents

6

Motivation

Bridging the gap:

​

Stakeholders

​

​

The need:

• Communicating requirements
• Having a basis for contracts and acceptance decisions

​

The means: Documented requirements

Text questions to (562) 684-8307

7

System builders

Today’s Lecture – How do we document what the SW should do?

• Work products
• Glossary
• Prototypes
• Aspects to be documented
• How to document
• Quality

Text questions to (562) 684-8307

8

Today’s Lecture – How do we document what the SW should do?

• Work products
• Glossary
• Prototypes
• Aspects to be documented
• How to document
• Quality

Text questions to (562) 684-8307

9

RE work products

DEFINITION. Work product – A recorded, intermediate, or final result of information generated in a work process.

Synonym: artifact

Text questions to (562) 684-8307

10

Work products – single requirements

• Sentence in natural language – expressing an individual requirement
• The control system shall prevent engine overspeed.

​

• User story – specifying a function or behavior from a stakeholder’s perspective
• As a skier, I want to pass the chairlift gate so that I get access without presenting, scanning, or inserting a ticket at the gate.

​

Text questions to (562) 684-8307

11

Work products – sets of requirements (I)

• Use case – specifying a system function from a stakeholder’s perspective

​

• Graphic model – specifying various aspects, e.g., context, activity, behavior

​

Text questions to (562) 684-8307

12

Work products – sets of requirements (II)

• Epic – providing a high-level view of a stakeholder need
• Let users create and manage their profile themselves.

​

• Feature – a distinguishing characteristic of a system that provides value for stakeholders
• Order history is downloadable by subscribers

​

Text questions to (562) 684-8307

13

Work products - documents

• System requirements specification
• Business requirements specification
• Stakeholder/user requirements specification

14

Classic requirements specifications

Full-fledged requirements specifications are typically needed…

• When customers want contractually-fixed requirements, costs and deadlines
• When systems are built by an external contractor based on a set of given requirements (outsourcing)
• In regulated environments where regulators check compliance of developed systems to their requirements

Text questions to (562) 684-8307

15

Work products - agile

Agile

• Product and sprint backlog – managing a list of work items, including requirements
• Story map – visual arrangement of user stories

Text questions to (562) 684-8307

16

Work products - other

• Glossary – providing an unambiguous and agreed-upon common terminology
• Textual note or graphic sketch – serving for communication and understanding
• Prototype – understanding or validating requirements

Text questions to (562) 684-8307

17

Today’s Lecture – How do we document what the SW should do?

• Work products
• Glossary
• Prototypes
• Aspects to be documented
• How to document
• Quality

Text questions to (562) 684-8307

18

Glossary

RE is typically a multi-person endeavor

• Danger of missing shared understanding in terminology

DEFINITION. Glossary – A collection of definitions of terms that are relevant in some domain.

A glossary defines:

• Context-specific terms
• Everyday terms that have a special meaning in the given context (business, application domain)
• Abbreviations and acronyms

Text questions to (562) 684-8307

19

Glossary Terms Brainstorming

• Go to www.menti.com and enter code

Text questions to (562) 684-8307

20

Today’s Lecture – How do we document what the SW should do?

• Work products
• Glossary
• Prototypes
• Aspects to be documented
• How to document
• Quality

Text questions to (562) 684-8307

21

Prototypes

DEFINITION. Prototype – A preliminary, partial realization of certain characteristics of a system.

• Serves for exploring, communicating or validating concepts and requirements.
• The realization may be in any physical form (paper/sticky notes, clickable pages, executable source code…)

​

In RE, a prototype is a means for:

• specifying requirements by example
• validating requirements
• supporting stakeholder communication and shared understanding

22

Today’s Lecture – How do we document what the SW should do?

• Work products
• Glossary
• Prototypes
• Aspects to be documented
• How to document
• Quality

Text questions to (562) 684-8307

23

Aspects to be documented (1)

Independently of any language, method, and documentation style, four aspects need to be documented:

1. Functionality
2. Quality
3. Constraints
4. Context/boundary

​

Text questions to (562) 684-8307

24

Functionality

Functionality aspects to be documented:

• Data
• Function and Flow
• State and Behavior
• Both normal and abnormal cases must be specified

Text questions to (562) 684-8307

25

Quality

Quality aspects to be documented:

• Performance
• Data volume
• Reaction time
• Processing speed
• Specify measurable values when possible
• Specific Qualities
• “-ilities” such as usability, reliability, availability, etc.

Text questions to (562) 684-8307

26

Constraints

Constraints (restrictions that must be obeyed / satisfied) to be documented:

• Technical
• Legal
• Organizational
• Cultural
• Environmental
• Physical
• Solutions/restrictions demanded by important stakeholders

Text questions to (562) 684-8307

27

Context/boundary

Context/boundary aspects to be documented:

• Domain requirements and domain assumptions in the context of a system
• Embedding of a system in its context
• Interaction between a system and the actors in the context

Text questions to (562) 684-8307

28

Canvas Quiz

​

​

Lecture 7: Functionality, Quality, Constraint, Context/boundary for GGSM

Text questions to (562) 684-8307

29

Today’s Lecture – How do we document what the SW should do?

• Work products
• Glossary
• Prototypes
• Aspects to be documented
• How to document
• Quality

Text questions to (562) 684-8307

30

How to document

Sample standards for classic requirements documents:

​

ISO/IEC/IEEE Std 29148

• Templates for business, stakeholder, system & software specs

​

VOLERE

• System and project requirements in 27 chapters

​

Enterprise-specific standards

• Imposed by customer or given by supplier

Text questions to (562) 684-8307

31

ISO/IEC/IEEE 29148 Standard

32

[ISO/IEC/IEEE (2018). Systems and Software Engineering — Life Cycle Processes — Requirements

Engineering. ISO/IEC/IEEE Standard 29148.]

VOLERE

33

[https://www.volere.org/templates/volere-requirements-specification-template/]

How to document – language options

Informally

• Plain natural language (narrative text)

​

Semi-formally

• Structured natural language (using templates or forms)
• Graphic models (diagrams with text)

​

Formally

• Formal models, typically based on mathematical logic and set theory

Text questions to (562) 684-8307

34

Example of Formal Specification: Z

35

[http://softeng.comlab.ox.ac.uk/usingz/exercises/exercises01/index.html]

Selective Use of Formal Specification

• Advantages:
• Unambiguous
• Makes verification provable
• Disadvantages:
• Requires training to use/understand
• Other techniques may be more cost-effective

​

• Use to specify the most critical sections of the requirements document
• Use to specify stable requirements

Text questions to (562) 684-8307

General rules for requirements documentation

• Specify requirements as small, identifiable units whenever possible
• Record metadata such as source, author, date, status
• Use structure templates
• Adapt the degree of detail to the risk associated with a requirement
• Specify normal and exceptional cases
• Don’t forget quality requirements and constraints

Text questions to (562) 684-8307

37

Minimize ambiguity as much as possible.

Level of Detail

What’s better?

• “The participant entry form has fields for last name, first name, gender, ...”
• “The participant entry form has the following fields (in this order): Last Name (40 characters, required), First Name (40 characters, required), Gender (three radio buttons labeled male, female, and non-binary; selections exclude each other, no default, required),...”

​

It depends.

• Degree of implicit shared understanding of problem
• Degree of freedom left to designers and programmers
• Cost vs. value of detailed specification
• The risk you are willing to take

Text questions to (562) 684-8307

38

Use more detail when…

• The work is being done for an external client
• Development or testing will be outsourced
• Project team members are geographically dispersed
• System testing will be based on requirements
• Accurate estimates are needed

Text questions to (562) 684-8307

39

Use less detail when…

• The work is being done internally for your company
• Customers are extensively involved
• Developers have considerable domain experience
• Precedents are available, as when a previous application is being replaced

Text questions to (562) 684-8307

40

Today’s Lecture – How do we document what the SW should do?

• Work products
• Glossary
• Prototypes
• Aspects to be documented
• How to document
• Quality

Text questions to (562) 684-8307

41

Quality of requirements (I)

For individual requirements and RE work products in general, strive for the following qualities:

• Correct: true and agreed stakeholder needs
• Understandable: prerequisite for shared understanding
• Verifiable: conformance of implementation can be checked
• Unambiguous: only one interpretation
• Complete: no missing parts
• Necessary: part of the relevant system scope
• Feasible: non-feasible requirements are a waste of effort

Text questions to (562) 684-8307

42

Quality of requirements (II)

• Consistent: no contradictions
• Complete: contains all the relevant requirements
• Conformant: conforms to prescribed structure/format/style
• Modifiable: because change will happen
• Non-redundant: requirements do not overlap
• Structured: improves readability of work product
• Traceable: linked/linkable to related artifacts

​

Text questions to (562) 684-8307

43

Not all qualities are equally important

• Correctness and understandability are most important
• Verifiability and consistency are also very important
• Achieving total completeness and unambiguity is neither possible nor economically feasible in most cases
• The importance of feasibility, traceability, conformance, etc. of requirements depends on the concrete project/situation

Text questions to (562) 684-8307

44

Summary

• Requirements are documented in various work products: sentences, user stories, graphic models, specification documents, product backlogs, sketches, prototypes, and more
• Choice of work products used is dependent on the situation
• Range from informal to formal
• Glossaries are crucial for promoting shared understanding
• In all RE situations, functionality, quality, constraints, and context/boundary must be documented
• Correctness and understandability are the most important qualities when documenting requirements
• Followed closely by verifiability and consistency

​

Text questions to (562) 684-8307

45