CHAPTER 4;
REQUIREMENTS DOCUMENTATION
WHAT SHOULD BE DOCUMENTED?
CONTEXT INFORMATION
ADDITIONAL INFORMATION
REQUIREMENTS
Scenarios
Quality Requirements
Goals
Subject facet, usage and IT system facet
Development context
RE context
Decision taken
Requirements change requests
Minutes of interview or meetings
DEFINITION
A document in requirements engineering serves a specific purpose. Depending on their purpose, documents differ in terms of context, format and quality
THREE KEY CHARACTERISTICS OF A DOCUMENT
FORMAT
QUALITY
CONTENT
level of detail
level of abstraction
Structure of document
Model-based
Combined
Textual
Quality properties
ACCEPTANCE CRITERIA
Defines verifiable and measurable conditions for accepting a development artefect
Acceptance testing: the implemented system will be verified against its specified requirements
Determine objectively if a requirement is satisfied
Acceptance criteria need to be defined, documented and communicated
Early definition of acceptance criteria during requirements engineering empowers the developer to consider the criteria when developing the system
FOR REQUIREMENTS
FOR THE IMPLEMENTED SYSTEM
Requirement specifications
Single requirements
Realization of entire system
Realization of single functions and qualities
typically refine quality criteria for sets of requirements as well as general documentation guidelines
can include acceptance criteria for single requirements
Define condition under which a requirement specification as a whole is accepted
Define the conditions a single requirements must meet in order to be accepted
refine quality criteria for single requirements as well as documentation guidelines
serve as basis for defining checklists for validation and verification.
define criteria the realization of a single functional or quality requirements must meet in order to be accepted during acceptance test
support the uncovering of potential defects in the requirement itself
define the conditions under which the client will accept the system
may be based on acceptance criteria for single requirements
AMBIGUITIES IN NL REQUIREMENTS
a: the quality or state of being ambiguous especially in meaning (see ambiguous)
b: a word or expression that can be understood in two or more possible ways: an ambiguous word or expression
uncertainty
SYNONYMS
obscurity
ambiguousness
AMBIGUITY IN RE
Natural language is inherently ambiguous
Two main reasons:
Under specified requirements
Defective specified requirements
R55: The system shall display the map quickly
vague, under specified statements lead to ambiguity
A response time of 1 second is neither clearly quick nor clearly slow
Syntactic
Semantic
Lexical
Synonyms
is caused by words with more than one meaning
Polysemy
Homonyms
The sentence has several different meanings
Coordination
Attachment
Elliptical
Analytical
A sentence has more than one interpretation in the specific context
Scope
Referential
Deictic
THREE TECHNIQUES FOR AVOIDING AMBIGUITY
Recommendation: Be aware of ambiguities and be careful in writing or in inspections
TECHNIQUES
Syntactic requirements patterns
Controlled languages (for Transformation Effects)
Glossaries
Using there techniques reduces the risk of writing ambiguous NL requirements
GLOSSARIES
a collection of techniques terms, which are part of a language (terminology). A glossary defines the specific meaning of each of these terms. A glossary can additionally contain references to related terms as well as examples that explain the terms
BENEFIT OF GLOSSARIES
Can be reused in follow up projects
can prevent lexical ambiguities, but only if everyone in the project/ organization uses the glossary as a main reference
CONTENT OF GLOSSARY
Content-specific technical terms
Abbreviations and acronyms
Everyday concepts that have a special meaning in the given context
RULES FOR WORKING WITH GLOSSARY
responsibilities must be defined
use must be obligatory
must be managed centrally
SYNTACTIC REQUIREMENTS PATTERNS
defines a syntactic structure for documenting requirements in natural language and defines the meaning of keywords used in the pattern
TRANSFORMATION DEFECTS IN NATURAL LANGUAGE REQUIREMENTS
CAUSES OF ERROR USING NATURAL LANGUAGE
Universal quantifiers
Incompletely specified conditions
Nouns without reference index
Incompletely specified process verbs
Normalization
A (normally long lasting) process is transformed into a single event
Consequence: Loss of information necessary to describe the process
Linguists call this a missing or inadequate index of reference
As with process verbs, nouns are frequently incompletely specified
Consequence: Missing information (eg: specific data)
Consequence: Even invalid data is processed
Specify amount of frequencies and define a set of objects. Danger, not all the objects should be treated the same way.
A potential loss of information
Consequence: Loss of information
Some verbs require more than a noun in the sentence to consider a requirements as complete
Suggestion : formulate requirements using active voice instead of passive voice