INGI 2355 Chapter 4 Requirements Specification and Documentation

1
INGI 2355Chapter 4 Requirements Specification
and Documentation
Alessio Lagonigro Nicolas Noël Thomas
Burette 03/10/2009
2
Content

• Where are we? (link with the others chapters)?
• Requirement document
• Good/Bad Requirement Document
• Notation kinds
• Free unrestricted in natural language
• Natural language with structure discipline
• Diagrammatic notation (semiformal)?
• Various diagrams

3
Introduction
4
Where are we?
5
Requirement Document
6
Requirement document (RD)?

• THE product of requirement engineering
• Contains
• Objectives
• Definitions
• domain properties
• Responsibilities
• system requirements
• software requirements
• environmental assumptions
• satisfaction requirement
• variants revisions
• acceptance data
• cost figures

7
Why bother?
Impact on subsequent work!
8
Target qualities of the RD

• Easy to understand
• Easy to follow dependency links
• Easy to Change
• In short Easy to useOnly useful if used!

9
Target qualities of RD contd

• Target qualities from chapter 1
• Completeness
• Consistency
• Adequacy
• Unambiguity
• Feasibility
• Good Structuring
• Modifiability

10
Requirements error

• Omission
• Contradiction
• Inadequacy
• Overspecification
• Ambiguity
• Noise
• Forward reference
• Remorse
• Unmeasurability
• Opacity

11
How to write the requirement document?

• Unstructured Natural Language
• Structured Natural Language
• Diagrammatic notation

12
Natural Language

• Advantages
• No expressivity limits
• Easily understandable by everybody
• No special training

13
Natural Language

• Inconvenience
• Prone to the defects mentioned earlier

14
Natural language

• Example 1 Ambiguity
• Le freinage maximum doit être appliqué par tout
  train qui
• reçoit une commande d'accélération expirée
• OU entre dans le bloque d'une gare à une vitesse
  supérieure à X km/h
• ET qui à un train le précédant de moins de Y
  mètres

What does that mean?
15
Natural language

• Example 2 And versus Or
• If case1 then ltstatement 1gt
• Or if Case2 then ltstatement2gt
• Vs
• If case1 then ltstatement 1gt
• And if Case2 then ltstatement2gt

16
Natural language

• Can you spot the tautology?
• If case1 then ltstatement 1gt
• Or if Case2 then ltstatement2gt
• (not case1 or statement1) or (not case2 or
  statement2)?

17
Natural language

• Can you spot the tautology?
• If case1 then ltstatement 1gt
• Or if Case2 then ltstatement2gt
• (not case1 or statement1) or (not case2 or
  statement2)?
• not(case1 and case2) or statement1 or statement2

18
Natural language

• Can you spot the tautology?
• If case1 then ltstatement 1gt
• Or if Case2 then ltstatement2gt
• (not case1 or statement1) or (not case2 or
  statement2)?
• not(case1 and case2) or statement1 or statement2
• Not false or statement or statement2

19
How to write the requirement document?

• Unstructured Natural Language
• Structured Natural Language
• Diagrammatic notation

20
Structured natural language

• Stylistic rules for text (technical writing)?
• Identify who will read this and write accordingly
• Does the reader follow the train of thoughts?
• Say what you are going to do before doing it.
• No more than one requirement, assumption or
  domain property per sentence
• Short sentences
• Shall mandatory , Should desirable
• No unnecessary jargon acronyms
• Use examples, tables, figures, equations to
  clarify
• Avoid nesting complex/ambiguous conditions
• (eg. the previous example)?

21
Structured natural language

• Decision table

Le freinage maximum doit être appliqué par tout
train qui reçoit une commande d'accélération
expirée OU entre dans le bloque d'une gare à une
vitesse supérieure à X km/h ET qui à un train le
précédant de moins de Y mètres
22
Structured natural language

• Predefined statement level template
• Statement identifier
• Statement category
• Specification (text of the statement itself
• using stylistic rule seen before)?
• Fit criterion
• Source of the statement
• Rationale
• Positive or Negative interaction with other
  statements
• Priority level
• Stability (change management)?

23
Structured natural language
Document level template

• Introduction
• ..
• ..
• General description
• ..
• ..
• Specific requirements
• ..
• ..

24
Structured natural language
Document level template

• Introduction
• Purpose of the requirements document
• Scope of the product
• Definitions, acronyms and abbreviations
• References
• Overview of the remainder of the document
• General description
• Product perspective
• Product functions
• User characteristics
• General constraints
• Assumptions and dependenciens
• Apportioning of requirements

25
Structured natural language

• ..
• ..
• Specific requirements
• Functional requirements
• External interface requirements
• Performance requirements
• Design constraints
• Software quality attributes
• Other requirements
• Appendices
• Index

26
How to write the requirement document?

• Unstructured Natural Language
• Structured Natural Language
• Diagrammatic notation

27
Diagrammatic notation

• Diagrammatic notation is an Alternative to
  (structured) natural language
• It is semi formal
• Formal items and inter-relationships
  declaration
• Informal description of properties in natural
  language
• Graphical communication with stakeholder
• Formal communication with machine

28
Myriad of notations

• There is a large amount of notations. Why these?
• Relevant to RE
• Cover complementary aspects of the RD
• Standard and widely used
• Based on UML

29
Context Diagram

• Given knowledge
• Components of the system
• Interactions between components
• Interaction Interfaces

30
Shared Phenomena

• Syntax semantic
• Box component
• Lines Shared phenomena

31
Context Diagram - limitations

• We cant know if a component monitor or control a
  shared phenomena ...

32
Problem diagrams

• Given knowledge
• Provide the same informations than the context
  diagram.
• Explicitly indicate which component
  monitor/control a shared phenomena
• Place the system-to-be on the diagram.
• Indicate the system requirements

33
Problem diagrams

• Syntax semantic
• Box component
• Lines Shared phenomena
• Rectangle with single stripe component to be
  designed.
• Rectangle with double stripe machine to build.
• Dashed oval requirement
• Dashed line the requirement refers the
  component
• Dashed arrow the requirement constrains the
  component
• Explicit indication of the component who
  monitor/control a shared phenomena.

34
Problem diagrams
35
Frame diagrams

• Generic problem diagram.
• Spécific notations for the differents types of
  notations.
• C causal component.
• B biddable component.
• X lexical component.

36
Frame diagrams
37
Entity-relationship diagrams

• Given knowledge
• The relationship between the components.
• Syntax semantic
• Entity class of concept instances.
• Attribute intrinsic feature of an entity.
• Relationship link several entity (with a arity).

38
Entity-relationship diagrams
39
SADT diagrams

• Given knowledge
• Data dependency link (actigrams)?
• Control dependency link (datagrams)?
• Can be analyzed by tools
• Rules of consistency and completeness can be
  checked.
• Rudimentary representation of events, trigger, ...

40
SADT actigram

• Syntax semantic
• Box system activity
• W and E arrows input and output data.
• N arrows Event or data controlling the
  activity.
• S arrows System component processing the
  activity.

41
SADT actigram
42
SADT datagram

• Syntax semantic
• Box data
• W and E arrows activity who produce and consume
  the data.
• N arrows activity controlling the data.
• S arrows resources needed to process the data.

43
SADT datagram
44
Dataflow diagrams

• Less expressive form of actigram
• Given knowledge
• Data dependency link.
• Syntax semantics
• Bubble operation.
• Arrows data flow.
• Double bar data repositories.
• Boxes begin of end of a data flow.
• Need precise definition of firing rules and
  synchronizing data transformation.

45
Dataflow diagram
46
Use case diagrams

• Given knowledge
• - Outline of the system to be.
• - Collect all the operation of a component to be.
• Syntax semantics
• - Not very clear.
• - Line interaction with a other component of an
  actor.

47
Use case diagram
48
Event Trace Diagram (Interaction scenario)?

• Given informations
• Behavior of the system components in time
• Interactions between the components
• Syntax
• Vertical line timeline of a component instance
• Orizzontal arrow Interaction between two
  components, controlled by the source and
  monitored by the target.

49
Event Trace Diagram (Interaction scenario)?
50
Event Trace Diagram (Interaction scenario)?

• Limit represents only one of the possible
  scenarios
• Cant represents negative scenarios
• Cant represents system which can have alternative
  evolutions.
• The only way is to write a ET for every possible
  scenario.

51
State Machine Diagram

• Given informations
• Evolution of the system status in time.
• Syntax
• Box State of the system.
• Arrow Transition from the source state to the
  target state.

52
State Machine Diagram

• Transitions
• A transition can be triggered in different ways
  when a certain time is passed, an external
  stimulus or random.
• Transitions can have a guard a condition that
  trigger the transition.
• A status can have multiple outgoing transition,
  so the system can have different evolutions (non
  deterministic behavior).

53
State Machine Diagram
54
State Machine Diagram Non deterministic behavior
55
State Machine Diagram Parallel behavior

• The state of the system can be a combination
• of the state of several independent ?variables
  that
• evolve in parallel, this is represented by
• the composition of different parallels state
  machines

56
R-net diagram

• Given informations
• All possible response of the system to one
  specific external stimulus.
• Syntax
• Hexagon input of the stimulus.
• Box operation consequent to the stimulus.
• Circle decision point, based on condition on the
  stimulus.
• Arrow precedence.
• An R-net diagram is always a directed tree.

57
R-net diagram
58
Integrating multiple system views.

• There are a lot of different diagrams
• Every diagram is a specific view of the system.
• Diagrams could have be done in different times
  and by different engineers.
• Changes of requirements can apparently affect
  only some of the views.
• So, is not always easy to maintain coherence
  through the various diagrams consistency rules
  are necessary!

59
Integrating multiple system views.

• Example of consistency rules
• Every interaction event in an ET scenario must
  appear in a corresponding SM diagram.

60
Integrating multiple system views.

• Example of consistency rules set
• Every component in a problem diagram must be
  specified in an ET diagram.
• Every shared phenomenon in a problem diagram must
  appear as an event in an ET diagram or as an
  entity, attribute or relationship in an ER
  diagram.
• Every data item in a DFD diagram must appear as
  an entity, attribute or relationship in an ER
  diagram.

61
Integrating multiple system views.

• Example of consistency rules set (follows)
• Every attribute carried by an interaction event
  in an ET scenario must be declared in an ER
  diagram.
• Every state in an SM diagram must correspond to a
  value for an attribute or relationship in an ER
  diagram.
• Events in an SM diagram that are not external
  stimuli to the component must correspond to
  operations performed by the component and
  declared in a DFD diagram.

62
Multiview specification in UML

• Among those diagrams, the most relevant for the
  multiview specification in the Requirements
  engineering process are
• Class diagram entity relationship view of the
  system.
• Use case diagram operational view.
• Sequence diagram view through the interactions.
• State machine diagram behavioral view of the
  whole system.

63
Stengths and limitations of diagrammatic notations

• Diagrammatic notations are semi-formal
  specification
• The formal part are the diagrams themselves,
  expressed in graphical language.
• The informal part is represented by the
  prescriptive and descriptive sentences that
  complete the system description, in structured
  natural language.

64
Strengths and limitations of diagrammatic
notations

• Strengths
• The graphical language is immediate and easy to
  read.
• The formalized standard made the diagrams
  processable by computers and maintainable in
  database.
• Every property contained or derived by the
  diagrams could be checked by query tools.

65
Strengths and limitations of diagrammatic
notations

• Limitations
• Formal descriptions could be limited to
  surface-level features, and a lot of properties
  are only described in the informal part of the
  RD.
• Graphical language has not always enough
  precision and can bring ambiguities.