REQUIREMENTS DOCUMENTATION
This section is quite well described in syllabus itself. Therefore the syllabus text is kept here
(it is in blue, but bit restructured). Additional information is in other colors.
EU 4.1 Document Design (L1)
In RE it is necessary to document all important information. All forms of more or less formal
representation of requirements, from the description in prose up to diagrams with formal
semantics, are called documentation techniques.
Many people are involved in the documentation in the lifecycle of a requirements
document. Documentation plays a goal-orientated supporting function in communication.
The following factors make this support necessary.
Requirements are long-lasting,
legally relevant
and should be accessible to all.
Requirements documents are complex.
In recent years documentations become more and more balanced in the sense that they can
include not only the text, but to the large extent also diagrams and even pieces of code. Thus
there is a movement towards model based requirements specifications. Different tools are
developed for requirements specification development and management. The simplest
adjusted tools are Jira and spreadsheets, the most sophisticated tools try to keep together
requirements as well as code. Examples of them are IBM DOORS Next Generation
http://www-03.ibm.com/software/products/lv/ratidoorng, and SystemWaver
http://www.systemweaver.se/modules/requirement-managment/.
EU 4.2 Documentation Types (L1)
Requirements documents include, amongst other things, functional requirements that
normally represent the following three different perspectives of a system.
Data perspective
Behavioral perspective
Functional perspective
All three perspectives can be documented by means of natural language requirements,
whilst conceptual model types are specialized for one of these perspectives. Effectively
applicable forms of the documentation are:
Natural language requirements documentation
Conceptual requirements models such as, for example use case diagrams, class
diagrams, activity diagrams or state diagrams
Combined forms of requirements documentation
EU 4.3 Document Structures (L1)
Central components of a requirements document are the requirements for the system being
considered. Besides the requirements, depending on the purpose of the document, the
requirements documents also contain information about the system context, acceptance
conditions or, for instance, characteristics of the technical implementation. In order to
ensure the manageability of requirements documents, such documents must be structured
most appropriately.
Reference structures for requirements documents propose a more or less complete and a
more or less flexible field-tested content structure. Common reference structures for
requirements documents are described amongst others in the Standard ISO/IEC/IEEE
29148:2011.
In practice it turns out that there are a lot of positive effects from using reference structures
for requirements documents. For instance, the use of reference structures simplifies the
usage of the requirements documents in subsequent development activities (e.g. in the
definition of test cases). Generally reference structures cannot be adopted one-to-one for a
requirements document, as the content structure frequently has to be adapted in detail for
domain-, company- or project-specific circumstances.
EU 4.4 Use of Requirements Documents (L1)
Requirements documents serve as the basis for many activities during the project lifespan,
such as, for example
Planning
Architectural design
Implementation
Test
Change management
System usage and system maintenance
Contract management
The documentation persistently amalgamates the information during the project and thus it
can serve as common reference, it can promote communication, promote objectivity,
support training of new employers, preserve expert knowledge, help to reflect the problems
etc.
The following things might be needed to be documented (K. Pohl's book)"
Agreement reached on requirements
Alternative solutions for conflicts
Brainstorming results
Change requests
Decision rationales
Decisions about change requests
Decisions regarding conflicts
Deviations from documentation rules/guidelines
Different stakeholder viewpoints
Evolution of artefacts
Identified contradictions
identified errors
Identified gaps in documented requirements
Identified requirements
Information about context aspects
Inspection rules
Interview results
New and innovative requirements
New context aspects
New requirements sources
Observation results
Outcomes of workshops and group meetings
Priorities
Prioritization of requirements
Process information
Responsible persons for activities
Requirements documentation in paper prototypes and sketches
Results of prototype usage
Results of walkthroughs
Review results
Risks
Scenarios that possibly resolve the conflicts
Stakeholder arguments
Stakeholder wishes and needs
Utilized context aspects
Utilized requirements sources
erc.
See additional information also in http://ijcsi.org/papers/IJCSI-10-5-1-223-228.pdf
It is essential to distinguish between requirements documentation and requirements
specification. Both shall comply to their rules. Documentation usually is more generic than
the specification. So the specification can be a part of documentations, which, in turn, can be
a part of all documented information.
EU 4.5 Quality Criteria for the Requirements Document (L2)
In order to serve as a basis the subsequent development processes, the requirements
document must meet certain quality criteria. In particular this includes:
Unambiguity and consistency [IEEE Std. 830-1998]
Clear structure
Modifiability and extensibility [IEEE Std. 830-1998]
Completeness [IEEE Std. 830-1998]
Traceability [IEEE Std. 830-1998]
EU 4.6 Quality Criteria for Requirements (L2)
In addition, the individual requirement must satisfy certain quality criteria, in particular:
agreed
unambiguous
necessary
consistent
verifiable
feasible
traceable
complete
understandable
Besides the quality criteria for requirements there are two basic style rules for
requirements in natural language, which promote readability:
short sentences and paragraphs and
formulate only one requirement per sentence.
In
http://www.utm.mx/~caff/doc/OpenUPWeb/openup/guidances/checklists/good_require
ments_594ACCBD.html the following quality checklist is offered
Is the requirement correct?
Does the requirement specify a true need, desire, or obligation?
Have you identified the root cause that necessitates the requirement?
Is the requirement complete?
Is the requirement stated as a complete sentence?
Is the requirement stated entirely in one place and in a manner that does not force the reader
to look at additional information to understand the requirement?
Is the requirement clear?
Is the requirement unambiguous and not confusing?
Does everyone agree on the meaning of the requirement?
Is the requirement consistent?
Is the requirement in conflict with other requirements?
Is the terminology used consistent with other requirement and glossary terms?
Is the requirement verifiable?
Can you determine whether the system satisfies the requirement?
Is it possible to define a clear, unambiguous pass or fail criterion?
Is it possible to determine whether the requirement has been met through inspection, analysis,
demonstration, or test?
Is the requirement traceable?
Is the requirement uniquely identified so that it can be referenced unambiguously?
Is the requirement feasible?
Can the requirement be satisfied within budget and on schedule?
Is the requirement technically feasible with current technology?
Is the requirement physically achievable?
Is the requirement design independent?
Are all requirements that impose constraints on the design, thereby limiting design
options, justified?
Is the requirement stated in such a way that there is more than one way that it can be
satisfied?
Is the requirement atomic?
Does the requirement statement define exactly one requirement?
Is the requirement statement free of conjunctions (and, or, but) that could indicate multiple
requirements?
See more on requirements quality in http://www.jot.fm/issues/issue_2005_11/column4.pdf
EU 4.7 Glossary (L2)
Afrequent cause of conflicts, arising in RE, lies in the different understanding of terminology
among the involved people. To prevent this problem, it is necessary that all relevant terms
are defined in a glossary. A glossary is a collection of term definitions for:
context-specific technical terms
abbreviations and acronyms
everyday concepts that have a special meaning in the given context
synonyms
homonyms
The following rules should be observed when working with a glossary:
The glossary must be managed centrally
The responsibilities for maintaining the glossary must be defined
The glossary must be maintained over the course of the project
The glossary must be commonly accessible
Use of the glossary must be obligatory
The glossary should contain the sources of the terms
The stakeholders should agree upon the glossary
The entries in the glossary should have a consistent structure
It is beneficial to begin the development of the glossary as early as possible, in order to
reduce the alignment work later on.
See more details on Glossary in http://www.bridging-the-gap.com/glossary/
