WORK PRODUCT I

Work Products in Requirements Engineering

• A recorded intermediate or final result generated in a work process.

• Stored electronically as files, databases, or RE tools.

• Can be represented in:

  • Natural language

  • Template-based

  • Model-based

  • Drawings or prototypes

• Will be discussed in subsequent topics.

Categories of Work Products

• Temporary

  • Created to support communication and shared understanding.

• Evolving

  • Grow in several iterations.

• Durable

  • Have been baselined or released.

Abstraction Levels

• Business requirements (high-level)

• System requirements (medium-level)

• Software components (detailed-level)

Level of Detail

Factors to consider the level of detail:

• The problem and development context.

• The degree of shared understanding of the problem.

• The degree of freedom left to designers and programmers.

• Availability of rapid stakeholder feedback during design and implementation.

• Cost vs value of a detailed specification.

• Imposed standards and regulatory constraints.

Aspects to be Considered

• Considering multiple aspects

  • Functional

  • Quality

  • Constraints

• Functional requirements focus on different aspects of a system:

  • Function and flow

  • Structure and data

  • State and behavior

• Requirements can only be understood in context:

  • System context

  • System boundary and external interfaces

Guidelines in Creating Documentation

• Select a work product type that fits the intended purposes

• Avoid redundancy by referencing content instead of repeating the same content

• Ensure that there are no inconsistencies between work products

• Use term consistently

• Structure work products appropriately

Plan the Documentation to be Used

• In which work products shall the requirements be recorded and what purpose?

• Which abstraction levels need to be considered?

• Up to which level of detail must requirements be documented on each abstraction level?

• How shall the requirements be represented in these documents?

Natural-Language-Based Documentation

Advantages of using natural language:

• Extremely expressive and flexible

• Used in everyday life, so no specific training is required to read and understand texts in natural language

Natural Language: Things to Avoid

• Incomplete descriptions

  • All place holders of the verb used must be fulfilled

  • Unspecific nouns

    • “The data shall be displayed for the user on the terminal.”

      • Which data exactly?

      • Which user exactly?

      • On which terminal exactly?

    • Examples:

      • the user, the controller, the system, the message, the data, the function

  • Unspecified amounts like the lines, the automobiles

    • “The system shall display the calculated data for the registered user, on the terminal on which he registered.”

  • Incomplete conditions

    • In the description of a condition, often the action is missing that should be taken if the condition is not fulfilled.

    • “In case of an error in the automated data transfer, the possibility must exist, to edit the individual fields of the x-picture.”

      • What possibility must exist if there is no error?

      • Which fields must be editable, all editable fields, or individual editable fields?

    • Trigger words:

      • If…then, in case, whether, depending on

  • Incomplete comparisons

    • “The new video app is much better”

      • Compared to?

      • What aspect?

Natural Language: Things to Handle with Care

• Passive voice

  • “The status of the items repaired will be updated”

• Universal quantifiers

  • Universal quantifiers specify amounts of frequencies and define a set of objects. Danger, that not all objects should be treated in the same way.

  • “Each message must be provided for the record with a time stamp.”

    • Really all messages?

  • Examples:

    • each, every, never, always, each time, in the evening

    • all, some, nothing, none

• Nominalizations

  • “In case of a system crash, a restart of the system shall be performed”

    • Who performs the system restart?

    • What exactly happens during a system restart?

    • The terms system crash and restart each describe a process that should be analysed more precisely.

  • Typical examples or nominalization: transmission, input, booking, acceptance.

  • Use nominalization only when the process behind it is fully defined (should be in the glossary)

Avoid Ambiguous Terms (1)

• Acceptable, adequate

  • Not verifiable

• As much as, reasonable

  • Not verifiable; better: still to quantify, to be done’

• At least, at most, fairly

  • Minimum and maximum have to be specified

• Between

  • The endpoints are including or excluding?

• Efficient

  • Not verifiable, allowed only on abstract level

• Quickly

  • Specify the speed

• Flexible

  • Better: describe the reaction of change

Avoid Ambiguous Terms (2)

• Corrected, better

  • Need to quantify

• Amongst others, similar to, not only

  • List of closed amount of possibilities

• Maximize, minimize, optimize

  • Specify quantifiable values

• Robust

  • Better: describe on how the system must react to errors

• Transparent, seamless, pleasant

  • List measurable properties

• Various

  • Specify measurable of quantifiable amounts

• Should not

  • Better: specify a positive list of allowed possibilities

Avoid Ambiguous Terms (3)

• State-of-the-art

  • Does not exist, tomorrow there will be something else

• Enough

  • Specify exact amount

• Supports, facilitates

  • The individual activities have to be specified

• User friendly, easy, uncomplicated

  • Usability must be described in detail ⇒ UI Prototyping

• Normal, ideally

  • Describe the normal developments and the deviations (alternatives)

• Understandably, if necessary, when appropriate

  • Specify the exact conditions, when something is appropriate

Template-based Documentation

• Used to overcome shortcomings of language-based documentation

• Provide pre-defined structures

• Phrase-template: pre-defined syntactic structure for a phrase that expresses a requirement, i.e., individual requirement or user-story

• Form template: pre-defined fields in a form to be filled e.g., writing a use case or measurable quality requirements

• Document template: pre-defined structure for a requirements document

Phrase Template: Individual Requirement

Phrase Template: Types of Requirements

• Ubiquitous requirements (must always hold):

  • The shall .

• Event-driven requirements (triggered by an external event):

  • WHEN the shall .

• Unwanted behavior (describing situations to be avoided):

  • IF , THEN the shall .

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

  • WHILE the shall .

• Optional features (applicable only if some feature is included in the system):

  • WHERE the shall .

Phrase Template: User Stories

• A User Story is a one-sentence description of a work-related task done by a user to achieve some goal or result

• Acceptance Criteria identify the features that must be present at the completion of the task

• The template for a user story description is: “As a I want to so that

User Stories

• Story ID:

• Story Title:

• Importance:

• User Story:

  • As a:

  • I want:

  • So that:

• Estimate:

• Acceptance Criteria

  • And I know I am done when:

• Type:

  • Search

  • Workflow

  • Manage Data

  • Payment

  • Report/View

• 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."

Sample User Story

• User Story

  • As a shipping clerk, I want to ship an order as accurately as possible as soon as the order details are available.

• Acceptance Criteria:

  • Available order details must pop up on the screen when available.

  • Portable display and scan device would cut time in half.

  • Sort the items by bin location.

  • Indicate the number of items in stock for each item and mark backorder for those not available.

  • Recommend shipper based on weight, size, and location.

  • Print out shipping label for selected shipper.

Form Template: Use Case Template

• Name

  • < A short active verb phrase>

• Precondition

• Success end condition

• Failed end condition

• Primary actor

• Other actors

• Trigger

• Normal flow

  • <Description of the main success scenario in a sequence of steps:

• Alternate flows

• Extensions

• Related information

Form Template: Measurable Quality Requirements

Document Template

• Part I: Introduction

  1. System purpose

  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

Advantages & Disadvantages of Template-based Documentation