Requirements Documentation

CSCI 5801: Software Engineering

Requirement Documentation

Requirement Documentation

• Unambiguous– Developers and clients have same understanding of

what system must do

• Understandable– Simple enough for clients to understand– Detailed enough for you to create system based on it

Definition vs. Specification

• Requirements definition– Stated from the viewpoint of somebody outside

the system (external viewpoint)– The system is a black box with some interface– The emphasis is on the role of the system

• Example: “The sprinkler never runs on rainy days”

Definition vs. Specification

• Requirements specification– Stated from the viewpoint of somebody inside the

system– The environment is accessed via inputs & outputs– The emphasis is on how the system works

• Example: “The controller will not engage the water pump any time the ambient water sensor is triggered.”

Definition vs. Specification

• Requirements documentation may contain both– Definition: best for customers– Specification best for developers

• Understand difference• If use both, make sure they agree

Scenarios

• Real-life examples of how system used– Single type of action taken by user and how system

responds (like user story in XP)– “Atomic” form of functional requirements

• Should include:– A description of the starting situation– A description of the normal flow of events– A description of what can go wrong– A description of the state when the scenario finishes

Common Scenario Components

• A unique name and simple one-sentence description• An initial assumption

– Preconditions that must be true at start of scenario

• A description of the normal steps – What user does and what system does in response

• A list of exceptions– What could go wrong, and what system must do

• System state upon completion of the scenario• Other simultaneous activities that could affect system• Any nonfunctional requirements

Example Scenario

“Fred wants to add CSIS 1590. He looks up the course on the system to get available sections. He likes the one at MWF 10 and selects it. His ID is added to the course roster”.

• What does student have to do before this?• How can student look up sections?• What if no open sections?• What is student does not like any of the open sections?• What can the student do next?• How does this relate to what other students are doing?

Example Scenario

Add ScenarioDescription: • A student adds a course by entering a course number

and selecting a section.Initial Assumption: • Student has logged in and navigated to ADD screen,

and has selected a course to add.

Example Scenario

Normal Steps:• System populates dropdown list of courses.• Student selects a course from the list.• A drop down with open sections (including their times) is

populated.• The student selects one and presses ADD.• The student is added to the course roster.• An acknowledgement of the add is displayed.• The student may add more courses, or exit to the main

menu.

Example Scenario

Exceptions: • All sections of the selected course may be closed, in which

case a message is popped up instead of the drop down being populated.

• The student may not like any of the open sections, in which case they can either enter another course or press CANCEL to return to the main menu.

• The course may be closed before the student presses ADD, due to other students adding, in which case a message is displayed and the list of open sections displayed again.

Example Scenario

System State upon Completion: • The student ID is added to the roster of the section

chosen. If that was the last remaining seat, the section is now closed.

Simultaneous activities:• Up to 500 other students may be adding and

dropping courses. This might result in courses closing while the student is in the process of adding this one. It might also affect response time.

Example Scenario

Nonfunctional Requirements: • On average a student who has registered for one

semester previously should make no more than 3 mistakes during an entire session and should be able to add all of their courses within 15 minutes.

• For requests for open sections, the system response time should be less than 2 seconds in 90% of cases under normal load.

Unified Modeling Language (UML)

Unified Modeling Language (UML)

• Graphical representations for design/analysis– How we tend to do design

• Common design specification language– Experienced developer should be able to immediately

understand system from diagram– Simple enough for customer to understand– Well-defined enough to allow developers to create system

Unified Modeling Language (UML)

• Based on earlier graphical representations– Entity Relationship diagrams (from database design)– Finite state machines– Data flow diagrams

• Controlled by OMG (Object Management Group) consortium– Latest version: UML 2

• UML 2 has 13 diagram types– Often loose semantics– Some types used more than others

Use Case Diagrams

• Define major roles of entities in system– Usually in terms of user activities– Actors that interact with system for that activity

Registration Use Cases

Use Case Refinement

• Can show overall use case as sequence of other use cases

Use Case Refinement

• Can extend general use case to more specific ones

Sequence Diagrams

• Define role of each object in overall use case– Each object has “lifeline”– Describe information passed/returned– May show options for multiple scenarios in same use case– Also used at design to show information flow inside system

Sequence Diagram

Mathematical Specifications

• The deceleration of the train shall be computed as:– Dtrain = Dcontrol + Dgradient

where Dgradient is 9.81ms2 * compensated gradient/alpha and where the values of 9.81ms2 /alpha are known for different types of train.

Tabular Specification

Condition Action

Sugar level falling (r2 < r1) CompDose = 0

Sugar level stable (r2 = r1) CompDose = 0

Sugar level increasing and rate of increase decreasing ((r2-r1)<(r1-r0))

CompDose = 0

Sugar level increasing and rate of increase stable or increasing. ((r2-r1) ≥ (r1-r0))

CompDose = round ((r2-r1)/4) If rounded result = 0 then CompDose = MinimumDose

IEEE requirements standard

• Defines a generic structure for a requirements– Introduction.

• General background and purpose of system

– General description• Requirements described at customer level

– Specific requirements.• Requirements described at developer level

– Appendices.– Index.

IEEE Standard 830

1. Introduction1.1. Purpose1.2. Scope1.3. Definitions, acronyms and abbreviations1.4. References1.5. Overview

27

Based on feasibility study

Glossary of possibly ambiguous termsCRN, course number, advisor, etc.

Sources of requirements (interviews, recordings, forms, etc.)

IEEE Standard 8302. General description

2.1. Product perspective

2.2. Product functions

2.3. User characteristics

2.4. Constraints2.5. Assumptions and dependencies

28

Hardware and software system will run on

List of features system will have (written at customer level)

Description of users of system, including knowledge of domain and experience with computing

IEEE Standard 830

3. Specific requirements3.1. External interface

requirements3.1.1. User interfaces

3.1.2. Hardware interfaces3.1.3. Software interfaces3.1.4. Comm. interfaces

29

General description of user interfaces, including layouts common to all scenarios, and general UI functional requirements such as training time

Descriptions of hardware (such as sensors), legacy software, and networks the system must work with

IEEE Standard 830

3.2. Functional requirements3.2.1. User class 1

3.2.1.1. Functional req. 1.1

3.2.1.2. Functional req. 1.2

...3.2.2. User class 2

…

30

Detailed description of individual use cases in whatever form appropriate (scenarios, sequence diagrams, etc.)

IEEE Standard 8303.3. Performance requirements3.4. Design constraints3.5. Software system attributes3.6. Other requirements

SE, Requirements Engineering, Hans van Vliet, ©2007 31

General non-functional requirements not directly related to any specific scenario, such as overall performance, general reliability, sustainability, etc.