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/