3.

Work Products and Documentation Practices

Traditional Requirements Engineering (RE) calls for the writing of a comprehensive,

complete, and unambiguous requirements specification [IEEE830], [Glin2016]. While
it is still appropriate to create fully-fledged requirements specifications in many
cases, there are also many other cases where the cost of writing such specifications
exceeds their benefit. For example, fully-fledged requirements specifications are
useful or even necessary when tendering or outsourcing the design and
implementation of a system or when a system is safety-critical and regulatory
compliance is required. On the other hand, where stakeholders and developers join
forces to define and develop a system iteratively, writing a comprehensive
requirements specification does not make sense. It is therefore vital in RE to adapt
the documentation to the project context and to select work products for
documenting requirements and requirements-related information that yield optimal
value for the project.
In this chapter, you will learn about the typical RE work products and how to create
them.

3.1 Work Products in Requirements Engineering

There are a variety of work products that are used in RE.

DEFINITION 3.1. WORK PRODUCT: A recorded intermediate or final result generated in a Work product
work process.
We consider the term artifact as a synonym for work product. We prefer the term Artifact
work product over artifact to express the connotation that a work product is the
result of work performed in a work process.
According to this definition, an RE work product can be anything that expresses
requirements, from a single sentence or diagram to a system requirements
specification that covers hundreds of pages. It is also important to note that a work
product may contain other work products.

3.1.1 Characteristics of Work Products

Work products can be characterized by the following facets: purpose, size, Characterization of work
representation, lifespan, and storage. products
Table 3.1 gives an overview of typical work products used in RE along with their
respective purpose (that is, what the work product specifies or provides) and typical
size. The table is structured into four groups: work products for single requirements,
sets of requirements, documentation structures, and other work products.
There are many different ways to represent a work product. In RE, representations Representation
based on natural language, templates, and models are of particular importance. These
are discussed in Sections 3.2, 3.3, and 3.4, respectively. There are further
representations, such as drawings or prototypes, which are covered in Section 3.7.
Every work product has a lifespan. This is the period of time from the creation of the Lifespan
work product until the point where the work product is discarded or becomes
irrelevant. We distinguish between three categories of work products with respect to
lifespan: temporary, evolving, and durable work products.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 25/139
Temporary work products are created to support communication and create shared Temporary work
understanding (for example, a sketch of a user-system interaction created in a products
workshop). Temporary work products are discarded after use; no metadata is kept
about these work products.
Evolving work products grow in several iterations over time (for example, a collection Evolving work products
of user stories that grows in both the number of stories and the story content). Some
metadata (at least the owner, status, and revision history) should be kept for every
evolving work product. Depending on the importance and status of a work product,
change control procedures need to be applied when modifying an evolving work
product.
Durable work products have been baselined or released (for example, a requirements Durable work products
specification that is part of a contract or a sprint backlog that is implemented in a
given iteration). A full set of metadata must be kept to manage the work product
properly and an elaborate change process must be followed to change a durable work
product (Chapter 6).
A temporary work product may become an evolving one when Requirements Temporary → Evolving
Engineers decide to keep a work product and develop it further. In this case, some → Durable
metadata should be added in order to keep the evolution of the work product under
control. When an evolving work product is baselined or released, it changes its
lifespan status from evolving to durable.
Table 3.1 Overview of RE work products

Work product Purpose: The work product specifies Size Typical RE work
/provides products

Single requirement
Individual requirement A single requirement, typically in textual form S
User story A function or behavior from a stakeholder’s S
perspective
Set of requirements
Use case A system function from an actor’s or user’s S-M
perspective
Graphic model Various aspects, for example, context, function, M
behavior (see Section 3.4)
Task description A task that a system shall perform S-M
External interface The information exchanged between a system M
description and an actor in the system context
Epic A high-level view of a stakeholder need M
Feature A distinguishing characteristic of a system S-M
Documents or documentation structures
System, business, stake- A comprehensive requirements document L-XL
holder, or user require-
ments specification
Product and sprint A list of work items, including requirements M-L
backlog
Story map A visual arrangement of user stories M
Vision A conceptual imagination of a future system M
Handbook for the CPRE Certified Professional for Requirements Engineering
Foundation Level - Version 1.0.0 Page 26/139
 Work product Purpose: The work product specifies Size
/provides
Other work products
Glossary Unambiguous and agreed common terminology M
Textual note or graphic A memo for communication and understanding S
sketch
Prototype A specification by example, particularly for S-L
understanding, negotiating, and validating
requirements
S: Small, M: Medium, L: Large, XL: Very large

Nowadays, most work products are stored electronically as files, in databases, or in Storing work products
RE tools. Informal, temporary work products may also be stored on other media—
for example, paper or sticky notes on a Kanban board.

3.1.2 Abstraction Levels

Requirements and their corresponding work products occur at various abstraction Requirements occur at
levels—from, for example, high-level requirements for a new business process, down various abstraction
to requirements at a very detailed level, such as the reaction of a specific software levels
component to an exceptional event.
Business requirements, domain requirements, and stakeholder/user requirements Typical layers: business,
typically occur at a higher level of abstraction than system requirements. When a system, components
system consists of a hierarchy of subsystems and components, we have system
requirements at the corresponding abstraction levels for subsystems and
components. As a consequence, requirements are frequently organized in three layers
of abstraction: the business, system, and component levels.
When business requirements and stakeholder requirements are expressed in durable Dependencies
work products—such as business requirements specifications, stakeholder
requirements specifications, or vision documents—they precede the specification of
system requirements. For example, in contractual situations, where a customer
orders the development of a system from a supplier, the customer frequently creates
and releases a stakeholder requirements specification. The supplier then uses this as
the basis for producing a system requirements specification. In other projects,
business requirements, stakeholder requirements, and system requirements may co-
evolve.
Some work products, such as individual requirements, sketches, or process models,
occur at all levels. Other work products are specifically associated with certain levels.
For example, a system requirements specification is associated with the system level.
Note that an individual requirement at a high abstraction level may be refined into
several detailed requirements at more concrete levels.
The choice of the proper abstraction level depends on what is to be specified. It is Choosing a proper
important, however, not to mix requirements that are at different abstraction levels. abstraction level
For example, in the specification of a healthcare information system, when writing a
detailed requirement about photos on client ID cards, the subsequent paragraph
should not state a general system goal such as reducing healthcare cost while
maintaining the current service level for clients. In small and medium-sized work
products, requirements should be at more or less the same abstraction level. In large
work products such as a system requirements specification, requirements at different
levels of abstraction should be kept separate by structuring the specification
accordingly (Section 0).
Handbook for the CPRE Certified Professional for Requirements Engineering
Foundation Level - Version 1.0.0 Page 27/139
Requirements naturally occur at different levels of abstraction. Selecting work
products that are adequate for a given level of abstraction and properly structuring
work products that contain requirements at multiple abstraction levels is helpful.

3.1.3 Level of Detail

When specifying requirements, Requirements Engineers have to decide on the level How much detail?
of detail in which the requirements shall be specified. However, deciding which level
of detail is appropriate or even optimal for a given requirement is a challenging task.
For example, in a situation where the customer and the supplier of a system
collaborate closely, it might be sufficient to state a requirement about a data entry
form as follows: “The system shall provide a form for entering the personal data of
the customer.” In contrast, in a situation where the design and implementation of the
system are outsourced to a supplier with little or no domain knowledge, a detailed
specification of the customer entry form will be necessary.
The level of detail to which requirements should be specified depends on several Factors affecting the
factors, in particular: level of detail needed
The problem and project context: the harder the problem and the less
familiar the Requirements Engineers and developers are with the project
context, the more detail is necessary.
The degree of shared understanding of the problem: when there is low
implicit shared understanding (see Principle 3 in Chapter 2), explicit,
detailed specifications are required to create the necessary degree of shared
understanding.
The degree of freedom left to designers and programmers: less detailed
requirements give the developers more freedom.
Availability of rapid stakeholder feedback during design and
implementation: when rapid feedback is available, less detailed
specifications suffice to control the risk of developing the wrong system.
Cost vs. value of a detailed specification: the higher the benefit of a
requirement, the more we can afford to specify it in detail.
Standards and regulations: Standards imposed and regulatory constraints
may mean that requirements have to be specified in more detail than would
otherwise be necessary.
There is no universally “right” level of detail for requirements. For every requirement,
the adequate level of detail depends on many factors. The greater the level of detail in
the requirements specified, the lower the risk of eventually getting something that
has unexpected or missing features or properties. However, the cost for the
specification increases as the level of detail increases.

3.1.4 Aspects to be Considered

Regardless of the RE work products being used, several aspects need to be considered
when specifying requirements [Glin2019].
First, as there are functional requirements, quality requirements, and constraints (see Considering multiple
Section 1.1), Requirements Engineers have to make sure that they cover all three aspects
kinds of requirements when documenting requirements. In practice, stakeholders
tend to omit quality requirements because they take them for granted.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 28/139
They also tend to specify constraints as functional requirements. It is therefore
important that the Requirements Engineers get this right.
When looking at functional requirements, we observe that they pertain to different Aspects within the
aspects, as, for example, a required data structure, a required order of actions, or the functional requirements
required reaction to some external event. We distinguish between three major
aspects: structure and data, function and flow, and state and behavior.
The structure and data aspect focuses on requirements concerning the static Structure and data
structure of a system and the (persistent) data that a system must know in order to
perform the required functions and deliver the required results.
The function and flow aspect deals with the functions that a system shall provide and Function and flow
the flow of control and data within and between functions for creating the required
results from given inputs.
The state and behavior aspect concentrates on specifying the state-dependent State and behavior
behavior of a system—in particular, how a system shall react to which external event
depending on the system’s current state.
When dealing with quality requirements, such as usability, reliability, or availability, a Quality requirements
quality model—for example, the model provided by ISO/IEC 25010 [ISO25010]—can
be used as a checklist.
Within the quality requirements, performance requirements are of particular
importance. Performance requirements deal with:
Time (e.g., for performing a task or reacting to external events)
Volume (e.g., required database size)
Frequency (e.g., of computing a function or receiving stimuli from sensors)
Throughput (e.g., data transmission or transaction rates)
Resource consumption (e.g., CPU, storage, bandwidth, battery)
Some people also consider the required accuracy of a computation as a performance
requirement.
Whenever possible, measurable values should be specified. When values follow a
probability distribution, specifying just the average does not suffice. If the
distribution function and its parameters cannot be specified, Requirements Engineers
should strive to specify minimum and maximum values or 95 percent values in
addition to the averages.
Documenting quality requirements beyond performance requirements is notoriously Difficulty of
difficult. documenting quality
Qualitative representations, such as “The system shall be secure and easy to use,” are requirements
ambiguous and thus difficult to achieve and validate.
Quantitative representations are measurable, which is a big asset in terms of
systematically achieving and validating a quality requirement. However, they raise
principal difficulties (for example, how can we state security in quantitative terms?)
and can be quite expensive to specify.
Operationalized representations state a quality requirement in terms of functional
requirements for achieving the desired quality. For example, a data security
requirement may be expressed in terms of a login function that restricts the access to
the data and a function that encrypts the stored data. Operationalized representations
make quality requirements testable but may also imply premature design decisions.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 29/139
The often-heard rule “Only a quantified quality requirement is a good quality
requirement” is outdated and may lead to quality requirements having low or even
negative value due to the high effort involved in the quantification. Instead, a risk-
based approach should be used [Glin2008].
Qualitative representations of quality requirements suffice in the following situations:
There is sufficient implicit shared understanding between stakeholders,
Requirements Engineers, and developers.
Stakeholders, Requirements Engineers, and developers agree on a known
solution that satisfies the requirements.
Stakeholders only want to give general quality directions and trust the
developers to get the details right.
Short feedback loops are in place such that problems can be detected early.
When developers are able to generalize from examples, specifying quality
requirements in terms of quantified examples or comparisons to an existing system
is a cheap and effective way of documenting quality requirements.
Only in cases where there is a high risk of not meeting the stakeholders’ needs,
particularly when quality requirements are safety-critical, should a fully quantified
representation or an operationalization in terms of functional requirements be
considered.
When specifying constraints, the following categories of constraints should be Constraints
considered:
Technical: given interfaces or protocols, components, or frameworks that Constraint categories to
have to be used, etc. be considered
Legal: restrictions imposed by laws, contracts, standards, or regulations
Organizational: there may be constraints in terms of organizational
structures, processes, or policies that must not be changed by the system.
Cultural: user habits and expectations are to some extent shaped by the
culture the users live in. This is a particularly important aspect to consider
when the users of a system come from different cultures or when
Requirements Engineers and developers are rooted in a different culture to
the system’s users.
Environmental: when specifying cyber-physical systems, environmental
conditions such as temperature, humidity, radiation, or vibration may have
to be considered as constraints; energy consumption and heat dissipation
may constitute further constraints.
Physical: when a system comprises physical components or interacts with
them, the system becomes constrained by the laws of physics and the
properties of materials used for the physical components.
Furthermore, particular solutions or restrictions demanded by important
stakeholders also constitute constraints.
Finally, requirements can only be understood in context (see Principle 4 in Chapter 2). Context and boundary
Consequently, a further aspect has to be considered, which we call context and
boundary.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 30/139
The context and boundary aspect covers domain requirements and domain
assumptions in the context of the system, as well as the external interfaces between
the system and its environment at the system boundary.
There are many interrelationships and dependencies between the aspects mentioned Interrelationships and
above. For example, a request issued by a user (context) may be received by the dependencies between
system via an external interface (boundary), trigger a state transition of the system aspects
(state and behavior), which initiates an action (function) followed by another action
(flow) that requires data with some given structure (structure and data) to provide a
result to the user (context) within a given time interval (quality).
Some work products focus on a specific aspect and abstract from the other aspects.
This is particularly the case for requirements models (Section 3.4). Other work
products, such as a system requirements specification, cover all these aspects. When
different aspects are documented in separate work products or in separate chapters
of the same work product, these work products or chapters must be kept consistent
with each other.
Many different aspects need to be considered when documenting requirements, in
particular, functionality (structure and data, function and flow, state and behavior),
quality, constraints, and surrounding context (context and boundary).

3.1.5 General Documentation Guidelines

Independently of the techniques used, there are some general guidelines that should General guidelines
be followed when creating RE work products:
Select a work product type that fits the intended purpose.
Avoid redundancy by referencing content instead of repeating the same
content again.
Avoid inconsistencies between work products, particularly when they cover
different aspects.
Use terms consistently, as defined in the glossary.
Structure work products appropriately—for example, by using standard
structures.

3.1.6 Work Product Planning

Each project setting and each domain is different, so the set of resulting work What to consider
products must be defined for each endeavor. The parties involved, particularly the
Requirements Engineers, stakeholders, and project/product owners or managers
need to agree upon the following issues:
In which work products shall the requirements be recorded and for what
purpose (see Table 3.1)?
Which abstraction levels need to be considered (Section 3.1.2)?
Up to which level of detail must requirements be documented at each
abstraction level (Section 3.1.3)?
How shall the requirements be represented in these work products (for
example, natural-language-based or model-based, see below) and which
notation(s) shall be used?

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 31/139
Requirements Engineers should define the RE work products to be used at an early Define RE work products
stage in a project. Such early definition: early
Helps in the planning of efforts and resources
Ensures that appropriate notations are used
Ensures that all results are recorded in the right work products
Ensures that no major reshuffling of information and “final editing” is
needed
Helps to avoid redundancy, resulting in less work and better maintainability

3.2 Natural-Language-Based Work Products

Natural language, in both spoken and written form, has always been a core means for Advantages
communicating requirements for systems. Using natural language to write RE work
products has many advantages. In particular, natural language is extremely
expressive and flexible, which means that almost any conceivable requirement in any
aspect can be expressed in natural language. Furthermore, natural language is used
in everyday life and is taught at school, so no specific training is required to read and
understand requirements written in natural language.
Human evolution has shaped natural language as a means for spoken communication Problems
between directly interacting people, where misunderstandings and missing
information can be detected and corrected rapidly. Hence, natural language is not
optimized for precise, unambiguous, and comprehensive communication by means of
written documents. This constitutes a major problem when writing technical
documentation (such as requirements) in natural language. In contrast to
communication in spoken natural language, where the communication is
contextualized and interactive with immediate feedback, there is no natural means
for rapidly detecting and correcting ambiguities, omissions, and inconsistencies in
texts written in natural language. On the contrary, finding such ambiguities,
omissions, and inconsistencies in written texts is difficult and expensive, particularly
for work products that contain a large amount of natural language text.
The problem can be mitigated to some extent by writing technical documentation Writing rules
consciously, following proven rules and avoiding known pitfalls.
When writing requirements in natural language, Requirements Engineers can avoid
many potential misunderstandings by applying some simple rules:
Write short and well-structured sentences. The rule of thumb is to express a Short sentences
single requirement in one sentence in natural language. To achieve a good
structure, Requirements Engineers should use phrase templates (Section
3.3).
Create well-structured work products. Besides writing well-structured Structured work
sentences (see above), work products written in natural language should products
also be well-structured as a whole. A proven way to do this is by using a
hierarchical structure of parts, chapters, sections, and subsections, as is
usually done in technical books. Document templates (Section 3.3) help you
to achieve a good structure.
Define and consistently use a uniform terminology. Creating and using a Uniform terminology
glossary (Section 3.5) is the core means for avoiding misunderstandings and
inconsistencies about terminology.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 32/139
 Avoid using vague or ambiguous terms and phrases. Vagueness, ambiguity
Know and avoid the pitfalls of technical writing (see below). Knowing the pitfalls

When writing technical documents in natural language, there are some well-known
pitfalls that should be avoided or things that need to be used with care (see, for
example, [GoRu2003]).
Requirements Engineers should avoid writing requirements that contain the Things to avoid
following:
Incomplete descriptions. Verbs in natural language typically come with a set Incomplete descriptions
of placeholders for nouns or pronouns. For example, the verb “give” has
three placeholders for who gives what to whom. When writing a requirement
in natural language, all placeholders of the verb used should be filled.
Unspecific nouns. Using nouns such as “the data” or “the user” leaves too Unspecific nouns
much room for different interpretations by different stakeholders or
developers. They should be replaced by more specific nouns or be made
more specific by adding adjectives or assigning them a well-defined type.
Incomplete conditions. When describing what shall be done, many people Incomplete conditions
focus on the normal case, omitting exceptional cases. In technical writing,
this is a trap to avoid: when something happens only if certain conditions are
true, such conditions shall be stated, providing both then and else clauses.
Incomplete comparisons. In spoken communication, people tend to use Incomplete comparisons
comparatives (for example, “the new video app is much better”) without
saying what they are comparing to, typically assuming that this is clear from
the context. In technical writing, comparisons should include a reference
object, for example, “faster than 0.1 ms”.
There are some further things that Requirements Engineers need to use with care, as Things to handle with
they constitute potential pitfalls: care
Passive voice. Sentences in passive voice have no subject. If a requirement is Passive voice
stated in the passive voice, this may hide who is responsible for the action
described in the requirement, leading to an incomplete description.
Universal quantifiers. Universal quantifiers are words such as all, always, or Universal quantifiers
never, which are used to make statements that are universally true. In
technical systems, however, such universal properties are rare. Whenever
Requirements Engineers use a universal quantifier, they need to reflect on
whether they are stating a truly universal property or whether they are
instead specifying a general rule that has exceptions (which they also need
to specify). They should apply the same caution when using “either-or”
clauses, which, by their semantics, exclude any further exceptional cases.
Nominalizations. When a noun is derived from a verb (for example, Nominalizations
“authentication” from “to authenticate”), linguists call this a nominalization.
When specifying requirements, Requirements Engineers need to handle
nominalizations with care because a nominalization may hide unspecified
requirements. For example, the requirement “Only after successful
authentication, the system shall provide a user access to (…)” implies that a
procedure for authenticating users exists.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 33/139
 When writing such a requirement, therefore, the Requirements Engineer
must check whether there are also requirements about the procedure for
authenticating legitimate users.
Natural language is a very powerful means for writing requirements. To mitigate the
inherent disadvantages of using natural language for technical documentation,
Requirements Engineers should follow proven writing rules and avoid well-known
pitfalls.

3.3 Template-Based Work Products

As mentioned in Section 3.2 above, using templates is a proven means for writing
good, well-structured work products in natural language and thus mitigating some of
the weaknesses of natural language for technical writing. A template is a kind of
ready-made blueprint for the syntactic structure of a work product. When using
natural language in RE, we distinguish between three classes of templates: phrase
templates, form templates, and document templates.

3.3.1 Phrase Templates

DEFINITION 3.2. PHRASE TEMPLATE: A template for the syntactic structure of a phrase Phrase template
that expresses an individual requirement or a user story in natural language.
A phrase template provides a skeleton structure with placeholders, in which
Requirements Engineers fill in the placeholders in order to get well-structured,
uniform sentences that express the requirements.
Using phrase templates is a best practice when writing individual requirements in
natural language and when writing user stories.

[Link] Phrase Templates for Individual Requirements

Various phrase templates for writing individual requirements have been defined, for ISO/IEC/IEEE 29148
example, in [ISO29148], [MWHN2009], and [Rupp2014]. The standard ISO/IEC/IEEE phrase template
29148 [ISO29148] provides a single, uniform template for individual requirements as
follows:
[<Condition>] <Subject> <Action> <Objects> [<Restriction>].

Example: When a valid card is sensed, the system shall display the “Enter your PIN”
message on the dialog screen within 200 ms.

When formulating an action with this template, the following conventions about the Using auxiliary verbs
use of auxiliary verbs are frequently used in practice:
Shall denotes a mandatory requirement.
Should denotes a requirement that is not mandatory but strongly desired.
May denotes a suggestion.
Will (or using a verb in the present tense without one of the auxiliary verbs
mentioned above) denotes a factual statement that is not considered as a
requirement.
When there are no agreed meanings for auxiliary verbs in a project, or when in doubt,
definitions such as the ones given above should be made part of a requirements
specification.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 34/139
EARS (Easy Approach to Requirements Syntax) [MWHN2009] provides a set of EARS templates
phrase templates that are adapted to different situations as described below.

Ubiquitous requirements (must always hold): The <system name> shall <system
response>.
Event-driven requirements (triggered by an external event):
WHEN <optional preconditions> <trigger> the <system name> shall
<system response>.
Unwanted behavior (describing situations to be avoided):
IF <optional preconditions> <trigger>, THEN the <system name>
shall <system response>.

Note: Although the unwanted behavior template is similar to the event-driven one, Mavin et al. provide
a separate template for the latter, arguing that unwanted behavior (primarily due to unexpected events
in the context, such as failures, attacks, or things that nobody has thought of), is a major source of
omissions in RE.

State-driven requirements (apply only in certain states):

WHILE <in a specific state> the <system name> shall <system response>.
Optional features (applicable only if some feature is included in the system):
WHERE <feature is included> the <system name> shall <system response>.
In practice, sentences that combine the keywords WHEN, WHILE, and WHERE may
be needed to express complex requirements.
EARS has been designed primarily for the specification of cyber-physical systems.
However, it can also be adapted for other types of systems.

[Link] Phrase Templates for User Stories

The classic phrase template for writing user stories was introduced by Cohn Cohn’s user story
[Cohn2004]: template

As a <role> I want <requirement> so that <benefit>.

Example: “As a line manager, I want to make ad hoc inquiries to the accounting system so
that I can do financial planning for my department.”
While Cohn has designated the <benefit> part of the template as optional, it is
standard practice nowadays to specify a benefit for every user story.
Every user story should be accompanied by a set of acceptance criteria—that is, Acceptance criteria
criteria that the implementation of the user story must satisfy in order to be accepted
by the stakeholders. Acceptance criteria make a user story more concrete and less
ambiguous. This helps to avoid implementation errors due to misunderstandings.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 35/139
3.3.2 Form Templates

DEFINITION 3.3. FORM TEMPLATE: A template providing a form with predefined fields to Form template
be filled in.
Form templates are used to structure work products of medium size such as use cases.
Cockburn [Cock2001] introduced a popular form template for use cases. [Laue2002]
proposed a template for task descriptions. Table 3.2 shows a simple form template
for use cases. Each flow step may be subdivided into an action by an actor and the
response by the system.

Table 3.2 A simple form template for writing use cases

Name < A short active verb phrase> Use case template

Precondition <Condition(s) that must hold when the execution of the
use case is triggered>
Success end condition <State upon successful completion of use case>
Failed end condition <State upon failed execution of use case>
Primary actor <Actor name>
Other actors <List of other actors involved, if any>
Trigger <Event that initiates the execution of the use case>
Normal flow <Description of the main success scenario in a
sequence of steps:
<step 1> <action 1>
<step 2> <action 2>
...
<step n> <action n> ... >
Alternate flows <Description of alternative or exceptional steps, with
references to the corresponding steps in the normal
flow>
Extensions <Extensions to the normal flow (if there are any), with
references to the extended steps in the normal flow>
Related information <Optional field for further information, such as
performance, frequency, relationship to other use
cases, etc.>
Form templates are also useful for writing quality requirements in a measurable form
[Gilb1988]. Table 3.2 provides a simple form template for measurable quality
requirements, along with an example.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 36/139
 Table 3.3 A form template for specifying measurable quality requirements

Measurable quality
Template Example
requirement template
ID <Number of R137.2
requirement>
Goal <Qualitatively stated Confirm room reservations immediately
goal>
Scale <Scale for measuring Elapsed time in seconds (ratio scale)
the requirement>
Meter <Procedure for Timestamping the moments when the
measuring the user hits the “Reserve” button and when
requirement> the app has displayed the confirmation.
Measuring the time difference.
Minimum <Minimum acceptable Less than 5 s in at least 95% of all cases
quality to be achieved>
OK range <Value range that is OK Between 0.5 and 3 s in more than 98% of
and is aimed at> all cases
Desired <Quality achieved in Less than 0.5 s in 100% of all cases
the best possible case>

3.3.3 Document Templates

DEFINITION 3.4. DOCUMENT TEMPLATE: A template providing a predefined skeleton Document template
structure for a document.
Document templates help to systematically structure requirements documents—for
example, a system requirements specification. RE document templates may be found
in standards, for example in [ISO29148]. The Volere template by Robertson and
Robertson [RoRo2012], [Vole2020] is also popular in practice. When a requirements
specification is included in the set of work products that a customer has ordered and
will pay for, that customer may prescribe the use of document templates supplied by
the customer. In

Figure 3.1, we show an example of a simple document template for a system

requirements specification.

3.3.4 Advantages and Disadvantages

Using templates when writing RE work products in natural language has major
advantages. Templates provide a clear, re-usable structure for work products, make
them look uniform, and thus improve the readability of the work products. Templates
also help you to capture the most relevant information and make fewer errors of
omission. On the other hand, there is a potential pitfall when Requirements Engineers
use templates mechanically, focusing on the syntactic structure rather than on
content, neglecting everything that does not fit the template.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 37/139
 Part I: Introduction Sample document
1. System purpose template
2. Scope of system development
3. Stakeholders
Part II: System overview
4. System vision and goals
5. System context and boundary
6. Overall system structure
7. User characteristics
Part III: System requirements
Organized hierarchically according to system structure, using a hierarchical
numbering scheme for requirements
Per subsystem/component:
• Functional requirements (structure and data, function and flow, state
and behavior)
• Quality requirements
• Constraints
• Interfaces
References
Appendices
Glossary (if not managed as a work product of its own)
Assumptions and dependencies

Figure 3.1 A simple system requirements specification template

Using templates when writing RE work products in natural language improves the
quality of the work products provided that the templates are not misused as just a
syntactic exercise.

3.4 Model-Based Work Products

Requirements formulated in natural language can easily be read by people provided Requirements in natural
they can speak the language. Natural language suffers from ambiguity due to the language have their
imprecision of semantics of words, phrases, and sentences [Davi1993]. This limitations
imprecision may lead to confusion and omissions in requirements. When you read
textual requirements, you will try to interpret them in your own way. We often try to
imagine these requirements in our mind. When the number of requirements is
manageable, it is possible to maintain insight and an overview of the textual
requirements. When the number of textual requirements becomes “too big,” we lose
the overview. That limit is different for each person. The number of textual
requirements is not the only reason for losing insight and overview. The complexity
of the requirements, the relationship between the requirements, and abstraction of
the requirements also contribute to this. You may have to read the requirements
formulated in natural language several times before you get a correct and complete
picture that the system must comply with. We have a limited ability to process
requirements in natural language.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 38/139
 Figure 3.2 Textual requirements versus modeled requirements

A model is an abstract representation of an existing part of reality or a part of reality A model is an abstract
to be created. Displaying the requirements (also) with a model (or picture) will representation of reality
contribute to readers grasping the requirements. Such diagrammatic representation
of a model is called a diagram.
The diagram in Figure 3.2 shows at a glance what the system must provide, but only Modeling requirements
if you have mastered the modeling language. It is evident that if you do not understand contributes to
the diagram, in this case a UML activity diagram, the picture will not contribute to a maintaining an overview
better understanding of the requirements. of and insight into the
In the next section (3.4.1), the concept of a requirements model is explained. Modeling requirements
of business requirements and goals is explained in Section [Link]. An important
method for describing the demarcation of a system is the context model. Examples of
the context are depicted in Section 3.4.2. Sections 3.4.3 to 3.4.5 give a number of
examples of modeling languages that are often used in systems engineering practice.

3.4.1 The Role of Models in Requirements Engineering

Like any language, a modeling language consists of grammatical rules and a

description of the meaning of the language constructs, see Section [Link]. Although a
model is a visual representation of reality, the language rules are important in order
to understand the model and the nuances in the model.
It is not always efficient or effective to summarize the requirements in a model. By
understanding the properties of a model, we can better determine when we can apply
which model, see Section [Link].
Just as natural language has advantages and disadvantages for expressing the
requirements, so do models. If we observe these facts in applying a model, we can
better determine the added value of applying the "correct" model. This is discussed
in Section [Link].

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 39/139
Many models have already been standardized and are used in various fields of
application, see Section [Link]. Consider, for example, the construction of a house,
where an architect uses a standardized model to describe the house. Another example
is electronics, where the drawing of electronic diagrams is standardized so that
professionals can understand, calculate, and realize the electronics.
To determine whether a diagram is applied correctly, we can validate the quality
criteria of a diagram. These criteria are described in Section [Link].

[Link] Syntax and Semantics

If you think about a natural language, for example your native language, it is defined A modeling language
by its grammar and semantics. consists of syntax and
The grammar describes the elements (words and sentences) and the rules that the semantics
language must obey. In a modeling language, this is called the syntax, see Figure 3.3.
The syntax describes which notation elements (symbols) are used in the language. It
also describes how these notation elements can be used in combination.

Figure 3.3 Modeling language syntax and semantics

The semantics defines the meaning of the notation elements and defines the meaning
of the combination of elements. Understanding the meaning of the notation elements
is fundamental for preventing the risk of the model being misinterpreted.

[Link] Properties of a Model

A requirements model is a conceptual model that depicts the requirements for the
system to be developed. A model is also used to represent the current situation to
understand, analyze, and explore the present problems. In this context, conceptual
means that reality is reduced to its essence. A model has a high level of abstraction
and reduces reality to what is relevant at this generic level.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 40/139
A conceptual modeling language can be standardized (internationally) and is then
referred to as a formal modeling language. An example of this is the widespread and
frequently applied modeling language UML (Unified Modeling Language).
A model has a number of properties that are explored further in the following
sections:
A model is made for a specific purpose.
A model gives a representation of reality.
A model is used to reduce information so that we can better understand
reality or focus on part of the reality.
A model is an abstract representation of an existing part of reality or a part of reality A model is an abstract
to be created. Reality can be presented from two angles, the descriptive and the representation of reality
prescriptive.
A descriptive model shows the current reality and reflects the requirements that are A model represents the
met. If no descriptive model is available yet, such a model is the result of the analysis reality in a descriptive or
of the current situation. Such a model is also called the original. prescriptive way
A prescriptive model indicates what future reality is expected or required. If a
descriptive model exists for the given situation, then the prescriptive model can be
derived from the original by indicating which requirements will be new, changed, or
are no longer needed. It describes the ultimate situation desired.
Reality can be complex. If we apply “too many” details, a model can be hard to grasp. A model reduces
This complex reality can be simplified by reducing the amount of information in the information
model. In a model, we can omit irrelevant information. Reducing the amount of
information can give us a better understanding of reality and allow us to understand
the essence of this reality more easily. Based on the intended purpose (first property)
for which the model is applied, only the relevant information is displayed in the
model.
Please note, if "too much" information is reduced, a clouded or incorrect image of
reality may arise. Thus, careful consideration should be given to how much of the
information can be reduced without distorting reality.
There are several ways to reduce information:
By compression or aggregation
Aggregating information is a way to make information more abstract. The
information is stripped of irrelevant details and is therefore more compact.
The information is, as it were, condensed.
By selection
By selecting only the relevant information, and not everything, it is possible
to indicate what the subject under consideration is. The focus is on a specific
part or number of parts of the total.
Both ways of reducing information can also be applied together.
A model is a representation of reality and each model represents certain aspects of A model suits a specific
reality. For example, a construction drawing shows the breakdown of the space in a purpose
building and an electrical diagram shows the wiring of the electrical circuit. Both
models represent the building for a specific purpose. A model is made for a specific
purpose in a specific context. In the example above, the context is the design and/or
realization of a building. The various construction drawings represent information
about a specific aspect of the building. This makes it immediately clear that a specific
model can be used only if it fits the purpose for which the model was made.
Handbook for the CPRE Certified Professional for Requirements Engineering
Foundation Level - Version 1.0.0 Page 41/139
[Link] Advantages and Disadvantages of Modeling Requirements

Compared with natural languages, models have the following advantages, among Advantages of models
others:
The elements and their connections are easier to understand and to
remember.
A picture tells more than a thousand words. A picture, and also a model, can
be easier to grasp and to remember. Note that a model is not self-
explanatory and needs extra information—i.e., a legend, examples, scenarios,
etc.
The focus on a single aspect reduces the cognitive load needed to
understand the requirements modeled.
Because a model has a specific purpose and a reduced amount of
information, understanding the reality modeled can require less effort.
Requirements modeling languages have a restricted syntax that reduces
possible ambiguities and omissions.
Because the modeling language (syntax and semantics) is simpler—i.e.,
limited number of notation elements and stricter language rules compared
with natural language—the risk of confusion and omissions is smaller.
Higher potential for automated analysis and processing of requirements.
Because a modeling language is more formal (limited number of notation
elements and stricter language rules) than a natural language, it lends itself
better to automating the analysis or processing of requirements.
Despite the great advantages for visualizing requirements with models, models also Disadvantages of
have their limitations. models
Keeping models that focus on different aspects consistent with each other is
challenging.
If multiple models are used to describe the requirements, it is important to
keep these models consistent with each other. This requires a lot of
discipline and coordination between the models.
Information from different models needs to be integrated for causal
understanding.
If multiple models are used, all models must be understood to enable a good
understanding of the requirements.
Models focus primarily on functional requirements.
The models for describing quality requirements and constraints are limited
if not lacking in specific context. These types of requirements should then be
supplied in natural language together with the models—for example, as a
separate work product.
The restricted syntax of a graphic modeling language implies that not every
relevant item of information can be expressed in a model.
Because a model is made for a specific purpose and context, it is not always
possible to record all requirements in the model or in multiple models.
Requirements that cannot be expressed in models are added to the model as
natural language requirements or as a separate work product.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 42/139
Therefore, requirements models should always be accompanied by natural language
[Davi1995].

[Link] Application of Requirements Models

As indicated in the previous sections, there are common models for various contexts.
For example, in architecture, you have construction drawings, piping diagrams,
electrical diagrams, etc. to express the specifications of a building. In other contexts—
for example, software development—there are modeling languages that are useful in
these types of context. An important aspect in applying models is to use models that
are common in the context or that have been specially developed for a specific
context.
Many modeling languages—for example, UML [OMG2017] or BPMN [OMG2013]—
have been standardized. When requirements are specified in a non-standard
modeling language, the syntax and semantics of the language should be explained to
the reader—for example, via a legend.
Models are used to describe the requirements from a certain perspective. In system
development, functional requirements are categorized in the following perspectives
(see also Section 3.1.4):
Structure and data
Models that focus on the static structural properties of a system or a domain
Function and flow
Models that focus on the sequence of actions required to produce the
required results from given inputs or the actions required to execute a
(business) process, including the flow of control and data between the
actions and who is responsible for which action
State and behavior
Models that focus on the behavior of a system or the life cycle of business
objects in terms of state-dependent reactions to events or the dynamics of
component interaction
The nature of the system being modified or built gives direction to the models to be The nature of a system
used. For example, if the nature of the system is to process information and helps in the selection of
relationships, then it is expected that there are quite a lot of functional requirements the appropriate model
that describe this information and these relationships. As a result, we use a matching
modeling language that lends itself to modeling data and its structure.
Naturally, a system will consist of a combination of the above perspectives. It follows
that a system needs to be modeled from multiple perspectives. Sections 3.4.3 to 3.4.5
elaborate the different models for each perspective in more detail.
Before the requirements are elicited and documented—for example with models—
an inventory is taken of goals and context. These can also be modeled, see Sections
[Link] respectively 3.4.2.
Applying models helps us mainly in the following ways:
Specifying (primarily functional) requirements in part or even completely, as
a means of replacing textually represented requirements
Decomposing a complex reality into well-defined and complementing
aspects; each aspect being represented by a specific model, helping us to
grasp the complexity of the reality

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 43/139
 Paraphrasing textually represented requirements in order to improve their
comprehensibility, in particular with respect to relationships between them
Validating textually represented requirements with the goal of uncovering
omissions, ambiguities, and inconsistencies
Modeling the requirements also helps with structuring and analyzing knowledge. You
can use diagrams to structure your own thoughts to get a better understanding of the
system and its context.

[Link] Quality Aspects of a Requirements Model

This is a supplementary section for which there will be no questions in the CPRE
Foundation level exam.
A substantial part of the requirements models are diagrams or graphical The quality of a model is
representations. The quality of the requirements model is determined by the quality determined by three
of the individual diagrams and their mutual relationships. In turn, the quality of the criteria
individual diagrams is determined by the quality of the model elements within the
diagrams. The quality of the requirements models and model elements can be
assessed against three criteria [LiSS1994]:
1. Syntactic quality
2. Semantic quality
3. Pragmatic quality
The syntactic quality expresses the extent to which a single model element (graphical Syntactic quality
or textual), requirements diagram, or requirements model complies with the
syntactic specifications. If, for example, a model that describes the requirements as a
class model contains modeling elements that are not part of the syntax, or model
elements are misused, then this will decrease the syntactic quality of the model. A
stakeholder of this model—for example, a tester—might misinterpret the
information that is represented by the model. This might eventually lead to
inappropriate test cases.
Requirements modeling tools provide facilities for checking the syntactic quality of
the models.
The semantic quality expresses the extent to which a single model element (graphical Semantic quality
or textual), the requirements diagram, or the requirements model correctly and
completely represents the facts.
Just like in natural language, semantics gives meaning to the words. If a term can have
different meanings or there are several terms that mean the same thing, this can lead
to miscommunication. The same applies to the semantics of modeling elements. If the
modeling elements are misinterpreted or applied incorrectly, the model may be
misinterpreted.
The pragmatic quality expresses the extent to which a single model element Pragmatic quality
(graphical or textual), the requirements diagram, or the requirements model is
suitable for the intended use—that is, whether the degree of detail and abstraction
level is appropriate for the intended use and whether the appropriate model is
selected with respect to the domain or context. This can be assessed if the purpose
and the stakeholders of the diagram are known. Intermediate versions of the model
can be submitted to the stakeholders interested to validate whether the diagrams fit
their purpose.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 44/139
During validation of the requirements, the quality of the modeling diagrams used is
assessed to make sure that these diagrams fit their intended purpose and usefulness.

[Link] Best of Both Worlds

As explained in the previous section, requirements that are expressed in textual or

visual/graphical form (i.e., via requirements models) have their advantages and
disadvantages. By using both textual and graphic representations of the
requirements, we can harness the power and benefits of both forms of representation.
Amending a model with textual requirements adds more meaning to the model. Document requirements
Another useful combination is that we can link quality requirements and constraints in natural language and
to a model or specific modeling element. This provides a more complete picture of the models to benefit from
specific requirements. the strengths of both
Using models can also support the textual requirements. Adding models and images approaches
to the textual requirements supports these models for a better understanding and
overview.

3.4.2 Modeling System Context

Chapter 2, Principle 4 introduces the notion that requirements never come in

isolation and that the system context, such as existing systems, processes, and users
need to be considered when defining the requirements for the new or changed
system.
Context models specify the structural embedding of the system in its environment, Context models help to
with its interactions to the users of the system as well as to other new or existing understand the context
systems within the relevant context. A context model is not a graphical description of and boundaries of a
the requirements but is used to reveal some of the sources of the requirements. Figure system
3.4 provides an abstract example of a system and its environment, with its interfaces
to the users of the system and its interfaces to other systems. Thus, context diagrams
help to identify user interfaces as well as system interfaces. If the system interacts
with users, the user interfaces must be specified in a later step during RE. If the system
interacts with other systems, the interfaces to these systems must be defined in more
detail in a later step. Interfaces to other systems may already exist or may need to be
developed or modified.

Figure 3.4 A system in its context

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 45/139
Even if there is no standardized modeling language for context models, context
models are frequently represented by:
Data flow diagrams from structured analysis [DeMa1978]
UML use case diagrams [OMG2017]
Note: the UML use case model consists of two elements; the use case
diagram (see Figure 3.6) and the use case specification (Section [Link]). This
chapter focuses on modeling with the use case diagrams.
Tailored box-and-line diagrams [Glin2019]
In the systems engineering domain, SysML block definition diagrams [OMG2018] can
be adapted to express context models by using stereotyped blocks for the system and
the actors.
In the next two subsections, we introduce the notation of data flow diagrams (DFD)
and UML use case diagrams to model the context of a system. These two examples do
not describe the complete context but emphasize the context from a specific
viewpoint.

[Link] Modeling the System Context with a Data Flow Diagram (DFD)

The system context can be viewed from different perspectives. The structured
analysis of systems [DeMa1978] talks about the context diagram. This diagram is a
special data flow diagram (DFD) where the system is represented by one process (the
system). Figure 3.5 shows an example of a context diagram.

Figure 3.5 Example of a context diagram using a DFD

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 46/139
The system is placed centrally in the model. It has a clear name so that the readers
know which system is being considered.
The rectangles around the system are terminators: customer, printer, and financial
administration. A terminator that provides information or services to the system is
called a source. A terminator that takes information or services from the system is
called a sink. A terminator can take either role depending on the data provided or
retrieved, such as the customer in the example above.
The arrows in the example show how the information from the terminators flows into A DFD gives insights into
the system (source) and from the system to the terminators (sinks). The arrows are the interface of the
given a logical name that describes what information is transferred. Irrelevant details system with its context
are omitted at the context diagram level. The information flow between the customer
and the system contains, for example, customer data. What information (name, date
of birth, email address, telephone number, delivery address, billing address, etc.)
makes up the customer data does not have to be relevant yet for this level of
abstraction.
The flow of information can consist of tangible (materials) and intangible
(information) objects. Also, at this conceptual level, there is no reference (yet) to
how—email, website, form, etc.—the information is provided.
Adding extra details to the context diagram can make it clearer to the stakeholders
involved and may help to improve the shared understanding. These details need to be
worked out for each individual situation.
Using a data flow diagram to model the context of a system provides some insights
into the interactions of the system with its environment, for example:
The interfaces to people, departments, organizations, and other systems in
the environment
The (tangible and intangible) objects that the system receives from the
environment
The (tangible and intangible) objects that is produced by the system and is
delivered to the environment
A data flow diagram indicates a clear boundary between the system and its
environment. The relevant users and systems of the environment are identified
during elicitation of requirements (Section 4.1). DFD context diagrams can help to
structure the context to reach a shared understanding of the system context and the
system boundary.

[Link] Modeling the System Context with a UML Use Case Diagram

Another view of the context of a system can be reached from a functional perspective.
The UML use case diagram is a common approach for modeling the functional aspects
of a system and the system boundaries, along with the system’s interactions with
users and other systems. Use cases provide an easy way to systematically describe
the various functions within the defined scope from a user perspective. This is
different to DFD context diagrams, where the system is represented as a big black box.
Use cases were first proposed as a method for documenting the functions of a system
in [Jaco1992]. The UML use cases consists of use case diagrams with associated
textual use case specifications (see Section 3.3.2). A use case specification specifies
each use case in detail by, for example, describing the possible activities of the use
case, its processing logic, and preconditions and postconditions of the execution of
the use case. The specification of use cases is essentially textual—for example, via use
case templates as recommended in [Cock2001].
Handbook for the CPRE Certified Professional for Requirements Engineering
Foundation Level - Version 1.0.0 Page 47/139
As mentioned, a UML use case diagram shows the functions (use cases) from the point A use case diagram
of view of the direct users and other systems that interact with the system under gives insights into the
consideration. The name of the use case is often composed of a verb and a noun. This functionality provided to
gives a brief description of the function offered by the system, as shown by the the direct users in the
example in Figure 3.6. context
The actors are the direct users or systems that interact with the system under
consideration. The actor (user or system) that starts the use case receives the benefit
that the use case delivers (e.g., showing the status of an order to the customer). The
association connects the actor with the relevant use case but it does not document
any direction or data flow (as is done in DFDs); it expresses only that the actor
receives the benefit from the use case.

Figure 3.6 Example of a context diagram using a use case diagram

A UML use case diagram describes the functionality that the system offers to its
environment. The separation between the functionality in the system and the actors
in the context is visualized with the system boundary (rectangle around the use cases,
e.g., “book ordering system”). Use case diagrams support sharpening of the system
boundary and checking whether the functional scope of the system at a high level is
covered.
Each use case also includes a detailed use case specification, documenting the
preconditions, trigger, actions, postconditions, actors, and so forth. Use cases are
usually described using a template (Section 3.3). If the scenarios of a use case become
complex or large, the recommendation is to visualize the scenarios with UML activity
diagrams, see Section [Link]. The detailed specification of use cases is not part of
context modeling and can be elaborated at a later time, when this information
becomes relevant.

3.4.3 Modeling Structure and Data

For functional requirements from the perspective of business objects (see Section
3.1.4), different data models are available. A (business) object can be a tangible or
intangible object, such as a bicycle, pedal, bicycle bell, but also a training request, a
shopping basket with digital products, and so on. A (business) object is "something"
in the real world. Some (or maybe all) of these (business) objects are used by the
system under consideration. The system uses these objects as input to process, to
persist, and/or to deliver output. Data models are used to describe the (business)
objects that must be known by the system. These kinds of diagrams model the object,
attributes of the object, and the relationships between objects. For the sake of
simplicity, we refer to modeling structure and data—these, however, represents
information structures between (business) objects in the real world.
Handbook for the CPRE Certified Professional for Requirements Engineering
Foundation Level - Version 1.0.0 Page 48/139
A number of common models for depicting structure and data are: Common models for
depicting structure and
Entity relationship diagrams (ERD) [Chen1976]
data
UML class diagrams [OMG2017]
SysML Block Definition Diagrams [OMG2018]
Building information models (BIM) [ISO19650]: these model the elements
required to plan, build, and manage buildings and other construction
elements. The details of models outside the system domain are not covered
by this handbook.
To explain the concept of modeling structure and data, this chapter uses the UML class
diagram as an example. UML, short for Unified Modeling Language, consists of an
integrated set of diagrams. This set of diagrams is a collection of best engineering
practices and has proven successful in modeling complex and large systems. UML was
designed by Grady Booch, James Rumbaugh, and Ivar Jacobson in the 1990s and it has
been a standardized modeling language since 1997.
If more depth or a different model is desired, read the literature referred to and
practice with the desired modeling language.

[Link] Modeling Structure and Data with UML Class Diagrams

UML is a collection of different models that can be used to describe a system. One of
these models is the class diagram. A class diagram depicts a set of classes and
associations between them. We discuss only the common and simple notation
elements of this model. If more depth is desired, we refer to the literature or the CPRE
Advanced Level Requirements Modeling.
In the overview below you will find the most common notation elements. Most common notation
elements of UML class
diagrams

Figure 3.7 Subset of the modeling elements of UML class diagrams

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 49/139
In a class model, you will find the concepts and terms that are relevant in the domain.
These concepts include a clear definition that is included in the glossary. With the use
of data models, the glossary is extended with information about the structure and
coherence of the terms and concepts. A clear definition and coherence of the terms
used prevents miscommunication about the matter under consideration.
Figure 3.8 shows a simplified model of the book ordering system (see examples of the
context in Section 3.4.2). The static information that the system needs to perform its
functionality—ordering a book—is modeled.
A customer orders a book and hence information is persisted for the classes Customer,
Order, and Book. A customer can place an order and therefore a relationship
(association) exists between the Customer and the Order. A customer can place
multiple orders over time and he/she only becomes a customer if he/she places an
order. This information determines the multiplicity: 1 customer places 1 or more
orders.
The fact that a customer can order a book means that there is also a relationship
between the classes Order and Book. To keep the example simple, here, the customer
can order only one book at a time. Also, an order must contain at least one book. An
order that has no book is not an order.
In the class Book, the attribute inStock is also maintained. Information such as ”if the
stock is not sufficient to fulfill the order, then a print job is sent to the printer” cannot
be modeled. This is a type of information that cannot be modeled in a class diagram
because it describes a certain functionality of the system. This information is part of
the requirements and should be documented in another work product. It can be
added as a textual requirement that accompanies the class diagram, or be modeled
with another diagram—for example, a UML activity diagram (see Section [Link]).

Figure 3.8 Example of a simple UML class diagram

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 50/139
3.4.4 Modeling Function and Flow

Function and flow describe how the (sub)system shall transform input into output.
We can visualize this type of requirement with models that depict function and flow.
Unlike modeling data, which essentially needs only one diagram type, function and
flow can be viewed from different angles. Depending on the needs of the stakeholders
to take the next step in the development process, more than one model might be
needed to document the requirements about function and flow.
Some common models for depicting function and flow are: Common models for
depicting function and
Business Process Modeling Notation (BPMN) [OMG2013]
flow
These process models are used to describe business processes or technical
processes. BPMN is frequently used to express business process models.
UML use case diagram [OMG2017]
See Section [Link].
UML activity diagram [OMG2017]
See Section [Link].
UML sequence diagram [OMG2017]
See Section [Link].
Data flow diagram [DeMa1978]
See Section [Link].
Domain story models [HoSch2020]
These models specify visual stories about how actors interact with devices,
artifacts, and other items in a domain, typically using domain-specific
symbols. They are a means for understanding the application domain in
which a system will operate.
To explain the concept of modeling function and flow, we limit this section to a few
examples of UML diagrams. If more depth or a different model is desired, read the
literature referred to and practice with the relevant modeling language.

[Link] UML Activity Diagram

UML activity models are used to specify system functions. They provide elements for
modeling actions and the control flow between actions. Activity diagrams can also
express who is responsible for which action. Advanced modeling elements (not
covered by this handbook) provide the means for modeling data flow.
A UML activity diagram expresses the control flow of activities of a (sub)system. Flow
thinking comes from visualizing program code with flow charts (according to
[DIN66001], [ISO5807]). This helped programmers to conceive and understand
complex structures and flows in programs. With the introduction of UML [OMG2017],
a model has been introduced for visualizing activities and actions from a functional
perspective.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 51/139
In the overview below you will find the basic notation elements. Basic notation elements
of UML activity
diagrams

Figure 3.9 Basic notation elements of the UML activity diagram

With this set of basic notation elements, you can set up a simple sequential activity
diagram. If more control is required, the model can be extended with decisions and
parallel flows of activities using the notation elements below.

Figure 3.10 Decisions and parallel flows in a UML activity diagram

Activity diagrams can be used to specify the processing logic of use case scenarios in
detail (see Section 3.3.2). Activity diagrams are created to visualize the scenarios,
which are processes with activities and processing logic. As long as the diagram
remains understandable, the main scenario can be modeled jointly with the
alternative scenarios and the exception scenarios as part of the same diagram.
Figure 3.11 gives a simple example of the book ordering system. This simplified flow
of action starts when the customer sends in their order. First, the Order and the
Customer information are validated to determine whether all (necessary) information
is supplied. If either the Order or the Customer information is invalid (incorrect or
insufficient), then a notification is sent to the customer and the order process is
canceled. The basic scenario is that the Order and Customer information are valid. The
scenario that the Order or Customer information is invalid is called an exceptional flow
and handles a functional faulty condition in the process.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 52/139
If both Order and Customer information are correct, then the stock is checked. If there
is a sufficient number of products in stock, the Order is picked and sent to the
Customer. An alternative flow is started if there are insufficient products in stock. A
print job request is sent to the Printer and a notification for a redelivery is sent to the
Customer.
Within the book ordering system, there are also other flows that are separated from
the order and delivery process. For example, the payment, redelivery, and invoice
processes have separate flows to allow a clear separation of concerns. If, for example,
the decision is taken to no longer keep any products in stock, then the order and
delivery process still applies. If changes are needed in this flow, these changes may
not affect the other flows. This decomposition of functionality helps to keep things
simple and clear.

Figure 3.11 Example of a UML activity diagram

3.4.5 Modeling State and Behavior

Functional requirements that describe the behavior, states, and transitions of a

(sub)system or that of a business object are requirements in the behavioral
perspective. An example of a system state is On, Standby, or Off. A business object can
have a life cycle that goes through a number of prescribed states. For example, a
business object Order can be in the following states: Placed, Validated, Paid, Shipped,
and Completed.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 53/139
A technique widely used to describe the behavior of a system is statecharts
[Hare1988]. Statecharts are state machines with states that are decomposed
hierarchically and/or orthogonally. State machines, including statecharts, can be
expressed in the UML modeling language [OMG2017] with state machine diagrams
(also called state diagrams).
State diagrams describe state machines that are finite. This means that these systems
eventually reach a final state. A state diagram shows the states that the system or an
object can take. It also indicates how to switch state—that is, the state transition. A
system does little by itself. Switching the state requires a trigger from the system or
from the environment of the system.
Common models for representing behavior and states include:
Statecharts [Hare1988]
UML state diagram [OMG2017]
To explain the concept of modeling behavior and states, this chapter uses the UML
state diagram as an example. If more depth or a different model is desired, read the
literature referred to and practice with the relevant modeling language.
In the overview below you will find the basic notation elements. Basic notation elements
of UML state diagrams

Figure 3.12 Basic notation elements of the UML state diagram

As discussed at the beginning of the section, a state diagram can clarify the states an
object can take. We see here an opportunity to visualize additional (and partly
redundant) information of an object. Imagine that you order a book on a website and
you want to track the status of your order. An order is used in the real world and is
modeled as a business object in a class diagram (see Figure 3.8) with, most likely, an
attribute status. The class diagram indicates that the attribute status can assume a
limited number of values, such as Validated, Paid, Delivered, Canceled, and so on. The
class diagram does not describe the order of possible status changes. A class diagram
does not describe the behavior of the system in a certain "status" either. This can be
made clear with a UML state diagram—for example, that an offered order cannot go
directly to the status Delivered without the customer having paid for the order.
Figure 3.13 gives an example of a state diagram of the book ordering system. In the
class diagram (Figure 3.8) of the book ordering system, an object Order is modeled.
This object has an attribute status that can have a limited number of values. These
values are listed and explained in the class diagram. What a class diagram does not
describe is the sequence in which the order is processed. A state diagram visualizes
the states and transitions between the states, making it clear what the sequence of
the order status is. The state diagram shows, for example, that the order cannot be
sent before it is completely picked (transition between the states Picked and Sent).
Handbook for the CPRE Certified Professional for Requirements Engineering
Foundation Level - Version 1.0.0 Page 54/139
Also, if the order is in the state Sent, the next state can only be Paid. A transition from
Sent to Handled is not possible. This diagram also makes clear that payment happens
after the book is sent. You can ask the stakeholders whether this is what they need or
have requested.
A transition may direct to the same status. This situation is visible in the state Picked.
Each time the order is not picked to completion, it stays in the same state to prevent
it from sending an incomplete order. Only when the order is completely picked is it
then sent to the customer.

Figure 3.13 Example of a UML state diagram

A few months after the release of the book ordering system, customers complained
that they did not have the ability to cancel an order. It was agreed that a customer
could cancel the order in each state of the order process. Modeling this new
requirement means that a transition to Canceled is needed from each state. This might
make the diagram difficult to read. Adding a textual requirement to describe this
behavior might be a way to keep the model simple for the audience.

[Link] UML Sequence Diagram

The following UML diagram is supplementary and will not be questioned in the CPRE
Foundation level exam.
The UML sequence diagram is used to depict the interaction between communication
partners and to model the dynamic aspect of systems. The communication partners
are actors, systems, components, and/or objects within a system.
The interaction displays the sequence of messages (a scenario) between these
communication partners. The interaction that takes place between the
communication partners realizes the purpose of a scenario, respectively (a part) of a
use case.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 55/139
In the overview below you will find the basic notation elements. Basic notation elements
of UML sequence
diagrams

Figure 3.14 Basic notation elements of the UML sequence diagram

A lifeline in a scenario depicts the role in the scenario, meaning the instance of an Basic notation elements
actor. When sequence diagrams are modeled, the instance name of an actor or object of messaging in UML
is often omitted. The roles that participate in the communication interact with each sequence diagrams
other by sending messages. There are two types of messages that are used in the
interaction.

Figure 3.15 Basic notation elements of messaging in the UML sequence diagram

A message can also be sent from or to objects outside the scenario. This is represented
as a filled-in circle. The sender or receiver of these kinds of messages may be
unknown.

Figure 3.16 Messages from and to an object outside the scenario

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 56/139
Figure 3.17 shows a model of the scenario in which a customer orders a book and that
specific book is out of stock. The Customer asks to place an Order. If the Order is
invalid, a notification that the Order is canceled is returned. If the Order is valid, the
stock is checked and if a book is out of stock, a print job is sent to the Printer. This is
an asynchronous message because it might take some time to print the book. A
notification is sent to the Customer that the book is out of stock and will be
redelivered. The Order is deactivated until the book is delivered by the Printer.
When the book is received from the Printer, the Order object is activated again. The
order is picked and sent to the Customer. This completes the Order and a last
notification of the status is sent to the Customer.

Figure 3.17 Example of a UML sequence diagram

3.4.6 Modeling Goals

Business requirements describe a business goal or need. They describe the end result
that the solution must meet and with which the (business) problem is solved, see
Chapter 2, Principle 5. To ensure that the focus is on solving the problem and that the
effort focuses on adding value, goals are carefully described. In Requirements
Engineering, there are several ways to document goals. The most common one is the
use of natural language (Section 3.2) or templates (Section 3.3). Template-based
documentation forms can be found, for instance, in [Pich2010], [Pohl2010], or
[RoRo2012].
There are also some model-based notations for documenting goals. The easiest and
most common notation is an AND/OR tree [AnPC1994]. AND/OR trees allow us to
document goals at different levels of detail and to link subgoals with goals using AND
and OR relationships. An AND relationship means that all subgoals need to be fulfilled
to fulfill the goal. An OR relationship is used to express that at least one of the subgoals
needs to be fulfilled to fulfill the goal.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 57/139
More academic modeling approaches for goals can be found in:
Goal-oriented requirements language (GRL) [GRL2020]
This is a language that supports goal-oriented modeling and reasoning of
requirements, especially for dealing with non-functional requirements.
Knowledge acquisition in automated specification (KAOS) [vLam2009]
KAOS is a methodology that contains goal modeling. This enables analysts to
build requirements models and to derive requirements documents from
KAOS goal models.

Documenting goals (in textual or graphical form) is an important starting point for
eliciting requirements, referring the requirements to their rationale, and identifying
sources—like stakeholders—of the requirements, etc.

3.5 Glossaries
Glossaries are a core means of establishing shared understanding of the terminology Why glossaries
used when developing a system: they help avoid people involved as stakeholders or
developers using and interpreting the same terms in different ways.
A good glossary contains definitions for all terms that are relevant for the system, be Glossary content
they context-specific terms or everyday terms that are used with a special meaning in
the context of the system to be developed. A glossary should also define all
abbreviations and acronyms used. If there are synonyms (that is, different terms
denoting the same thing), they should be marked as such. Homonyms (that is,
identical terms that denote different things) should be avoided or at least marked as
such in the glossary.
There are a couple of rules that guide the creation, use, and maintenance of the Glossary rules
glossary in a system development project.
1. Creation and maintenance. To ensure that the terminology defined in the glossary
is consistent and always up to date, it is vital that the glossary is managed and
maintained centrally over the entire course of a project, with one person or a
small group being responsible for the glossary. When defining terms, it is
important that the stakeholders are involved and agree on the terminology.
2. Usage. In order to get the full benefit of a glossary, its use must be mandatory.
Work products should be checked for proper glossary usage. Obviously, this
means that everybody involved in a project must have read access to the
glossary.
When an organization develops related systems in multiple projects, it makes sense
to create a glossary at the enterprise level in order to achieve consistent terminology
across projects.
Creating, maintaining, and using a glossary consistently avoids errors and
misunderstandings concerning the terminology used. Working with glossaries is a
standard best practice in RE.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 58/139
3.6 Requirements Documentation Structures

It is not sufficient to work with requirements at the level of individual requirements. Documents and
Requirements must be collated and grouped in suitable work products, be they documentation
explicit requirements documents or other RE-related documentation structures structures
(such as a product backlog).
Document templates (see Section 3.3.3) may be used to organize such documents Document templates
with a well-defined structure in order to create a consistent and maintainable
collection of requirements. Document templates are available in literature
[Vole2020], [RoRo2012] and in standards [ISO29148]. Templates may also be reused
from previous, similar projects or may be imposed by a customer. An organization
may also decide to create a document template as an internal standard.
A requirements document may also contain additional information and
explanations—for example, a glossary, acceptance criteria, project information, or
characteristics of the technical implementation.
Frequently used
Frequently used requirements documents are:
documents
Stakeholder requirements specification: the stakeholders’ desires and needs
that shall be satisfied by building a system, seen from the stakeholders’
perspective. When a customer writes a stakeholder requirements
specification, it is called a customer requirements specification.
User requirements specification: a subset of a stakeholder requirements
specification, covering only requirements of stakeholders who are
prospective users of a system.
System requirements specification: the requirements for a system to be built
and its context so that it satisfies its stakeholders’ desires and needs.
Business requirements specification: the business goals, objectives, and needs
of an organization that shall be achieved by employing a system (or a
collection of systems).
Vision document: a conceptual imagination of a future system, describing its
key characteristics and how it will create value for its users.
Frequently used alternative documentation structures are: Frequently used
documentation
Product backlog: a prioritized list of work items, covering all requirements
structures
that are needed and known for the product
Sprint backlog: a selected subset of a product backlog with work items that
will be realized in the next iteration
Story map: a visual two-dimensional organization of user stories in a product
backlog with respect to time and content
There is no standard or universal requirements document or documentation Choosing a proper
structure. Accordingly, documents or documentation structures should not be reused documentation form
from previous projects without reflection. The actual choice depends on several
factors, for example:
The development process chosen
The project type and domain (for example, tailor-made solution, product
development, or standard product customizing)

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 59/139
 The contract (a customer may prescribe the use of a given documentation
structure)
The size of the document (the larger the document, the more structure is
needed)

3.7 Prototypes in Requirements Engineering

Prototypes play an important role both in engineering and design.

DEFINITION 3.5 PROTOTYPE: 1. In manufacturing: A piece which is built prior to the start Prototype
of mass production. 2. In software and systems engineering: A preliminary, partial
realization of certain characteristics of a system. 3. In design: A preliminary, partial
instance of a design solution.
Prototypes in software and systems engineering are used for three major purposes
[LiSZ1994]:
Exploratory prototypes are used to create shared understanding, clarify requirements, Exploratory prototype
or validate requirements at different levels of fidelity. Such prototypes constitute
temporary work products that are discarded after use. Exploratory prototypes may
also be used as a means of specification by example. Such prototypes must be treated
as evolving or durable work products.
Experimental prototypes (also called breadboards) are used to explore technical Experimental prototype
design solution concepts, in particular with respect to their technical feasibility. They
are discarded after use. Experimental prototypes are not used in RE.
Evolutionary prototypes are pilot systems that form the core of a system to be Evolutionary prototype
developed. The final system evolves by incrementally extending and improving the
pilot system in several iterations. Agile system development frequently employs an
evolutionary prototyping approach.
Requirements Engineers primarily use exploratory prototypes as a means for Prototypes in RE
requirements elicitation and validation. In elicitation, prototypes serve as a means of
specification by example. In particular, when stakeholders cannot express what they
want clearly, a prototype can demonstrate what they would get, which helps them
shape their requirements. In validation, prototypes are a powerful means for
validating the adequacy (see Section 3.8) of requirements.
Exploratory prototypes can be built and used with different degrees of fidelity. We
distinguish between wireframes, mock-ups, and native prototypes.
Wireframes (also called paper prototypes) are low-fidelity prototypes built with Wireframe
paper or other simple materials that serve primarily for discussing and validating
design ideas and user interface concepts. When prototyping digital systems,
wireframes may also be built with digital sketching tools or dedicated wireframing
tools. However, when using a digital tool for wireframing, it is important to retain the
essential properties of a wireframe: it can be built quickly, modified easily, and does
not look polished nor resemble a final product.
Mock-ups are medium-fidelity prototypes. When specifying digital systems, they use Mock-up
real screens and click flows but without real functionality. They serve primarily for
specifying and validating user interfaces. Mock-ups give users a realistic experience
of how to interact with a system through its user interface. They are typically built
with dedicated prototyping tools.
Native prototypes are high-fidelity prototypes that implement critical parts of a Native prototype
system to an extent that stakeholders can use the prototype to see whether the
prototyped part of the system will work and behave as expected.
Handbook for the CPRE Certified Professional for Requirements Engineering
Foundation Level - Version 1.0.0 Page 60/139
They serve both for specification by example and for thorough validation of critical
requirements. Native prototypes may also be used to explore and decide about
requirements variants for some aspect—for example, two different possible ways of
supporting a given business process.
Depending on the degree of fidelity, exploratory prototypes can be an expensive work
product. Requirements Engineers have to consider the trade-off between the cost of
building and using prototypes and the value gained in terms of easier elicitation and
reduced risk of inadequate or even wrong requirements.

3.8 Quality Criteria for Work Products and Requirements

Obviously, Requirements Engineers should strive to write good requirements that Many approaches
meet given quality criteria. RE literature and standards provide a rich set of such
quality criteria. However, there is no general consensus about which quality criteria
shall be applied for requirements. The set of criteria presented in this subsection aims
to provide a proven practice at foundation level.
Modern RE follows a value-oriented approach to requirements (see Principle 1 in
Chapter 2). Consequently, the degree to which a requirement fulfills the given quality
criteria shall correspond to the value created by this requirement. This has two
important consequences:
Requirements do not have to fully adhere to all quality criteria. No universal fulfillment
Some quality criteria are more important than others.
We distinguish between quality criteria for single requirements and quality criteria
for RE work products such as RE documents or documentation structures.
For single requirements, we recommend using the following quality criteria: Quality criteria for single
requirements
Adequate: the requirement describes true and agreed stakeholder needs.
Necessary: the requirement is part of the relevant system scope, meaning
that it will contribute to the achievement of at least one stakeholder goal or
need.
Unambiguous: there is a true shared understanding of the requirement,
meaning that everybody involved interprets it in the same way.
Complete: the requirement is self-contained, meaning that no parts
necessary for understanding it are missing.
Understandable: the requirement is comprehensible to the target audience,
meaning that the target audience can fully understand the requirement.
Verifiable: the fulfillment of the requirement by an implemented system can
be checked indisputably (so that stakeholders or customers can decide
whether or not a requirement is fulfilled by the implemented system).
Adequacy and understandability are the most important quality criteria. Without
them, a requirement is useless or even detrimental, regardless of the fulfillment of all
other criteria. Verifiability is important when the system implemented must undergo
a formal acceptance procedure.
Some people use correctness instead of adequacy. However, the notion of correctness
implies that there is a formal procedure for deciding whether something is correct or
not. As there is no formal procedure for validating a documented requirement against
the desires and needs that stakeholders have in mind, we prefer the term adequacy
over correctness.
Handbook for the CPRE Certified Professional for Requirements Engineering
Foundation Level - Version 1.0.0 Page 61/139
For work products covering multiple requirements, we recommend applying the Quality criteria for RE
following quality criteria: work products
Consistent: no two requirements, recorded in a single work product or in
different work products, contradict each other.
Non-redundant: each requirement is documented only once and does not
overlap with another requirement.
Complete: the work product contains all relevant requirements (functional
requirements, quality requirements, and constraints) that are known at this
point in time and that are related to this work product.
Modifiable: the work product is set up in such a way that it can be modified
without degrading its quality.
Traceable: the requirements in the work product can be traced back to their
origins, forward to their implementation (in design, code, and test), and to
other requirements they depend on.
Conformant: if there are mandatory structuring or formatting instructions,
the work product must conform to them.

3.9 Further Reading

Mavin et al. [MWHN2009] introduce and describe the EARS template. Robertson and
Robertson [RoRo2012] describe the Volere templates. Goetz and Rupp [GoRu2003],
[Rupp2014] discuss rules and pitfalls for writing requirements in natural language.
Cockburn [Cock2001] has written an entire book about how to write use cases.
Lauesen [Laue2002] discusses task descriptions and also provides some examples of
real-world RE work products.
The ISO/IEC/IEEE standard 29148 [ISO29148] provides many resources concerning
RE work products: phrase templates, quality criteria for requirements, and detailed
descriptions of the content of various RE work products, including a document
template for every work product. Cohn [Cohn2010] has a chapter on how to frame
requirements in a product backlog.
Gregory [Greg2016] and Glinz [Glin2016] discuss the problem of how detailed
requirements should be specified and to what extent complete and unambiguous
requirements specifications are possible.
Numerous publications deal with using models to specify requirements. The UML
specification [OMG2017], as well as textbooks about UML, describe the models
available in UML. Hofer and Schwentner [HoSch2020] introduce domain modeling
with domain storytelling. [OMG2013] and [OMG2018] describe the modeling
languages BPMN for modeling business processes and SysML for modeling systems,
respectively. The books by Booch, Rumbaugh, and Jacobson [BoRJ2005], [JaSB2011],
[RuJB2004] give more depth and (practical) applications of UML. Furthermore, the
following books and articles are recommended for more thorough knowledge and
patterns in modeling requirements: [DaTW2012], [Davi1993], [Fowl1996],
[GHJV1994]. [LiSS1994] and [Pohl2010] provide a better understanding of the quality
aspects of models.

Handbook for the CPRE Certified Professional for Requirements Engineering

Foundation Level - Version 1.0.0 Page 62/139