Requirements Document Pag.

1/13

Requirements Document Template

for Software Development Projects

Version 1.0 – 28th January 2008

by Adriano Comai – www.analisi-disegno.com

This template is licensed under a Creative Commons Attribution-

Non-commercial 3.0 Unported License.

Foreword of document or template, I hope you will

anyway find in this template some useful
suggestion. For people involved in an
Goal of this template
already started project, or maintaining an
The goal of this template is to provide existing software system, the template may
useful suggestions for the documentation also be used as a checklist for missing
of software requirements in a development aspects.
project.
The template does not contain any specific
Requirements of a software system may be treatment of contractual aspects (rules
documented, or not. There may be many governing the client-supplier relationship)
reasons not to document software and validations (acceptance by the client
requirements, but we don't need to discuss and other stakeholders of a specification),
it here. This template is for those who need because these characteristics depend on
to document requirements. the specific organizational contexts, and
can't be treated in general terms.
Software requirements may be
documented in different ways. There is not Structure of the template
a single universal standard for
This template is a composition of various
documenting requirements.
sections. Each section can be a separate
The documentation of requirements is
document, or remain just a section of the
usually more or less formalized depending
single composite document. Each section
on the criticality of the product to be
may be more or less formalized, depending
developed.
on your needs and preferences. What's
If your product is life critical, that is if a
more, each section may be used or not
software malfunction may harm people,
used, again depending on your needs and
you need a very thorough and formalized
preferences.
management of software requirements. In
this case, don't use this template. This
The main sections are:
template is intended for use in non-life-
 Vision
critical software projects.
 Release Plan
 Software requirements specification
If you already use or need to use another -
 Glossary - Data Repository
internal or industry-specific - existing type

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 2/13

system shall...”). Some of them

The Vision is a high level system specify a system functionality, and
specification. In its simplest form, it may be are called functional requirements.
a two-pages product data sheet. In its most Others specify other types of
complex form, it may be a 20 pages characteristics for the system (like
executive-level system description. usability, performance, reliability
It is the main communication medium level, internationalization) and are
among stakeholders about the work to be called non-functional requirements,
done. It contains no details. or quality attribute requirements.

The Release plan specifies the releases The form of the specification may vary from
planned for the system, and other high- the most informal (index cards for user
level milestones if significant for the client. stories to post on a wall) to the formal
Whenever possible, it is a good strategy to (several documents with hundreds or
build and ship the system incrementally, thousands of pages).
according with client's priorities and
system's architecture. The release plan The Glossary - Data Dictionary section
can and must be changed, whenever client deals with informations and data. It may be
and developers need to change it. specified at different complexity levels,
depending on actual needs.
Every project, even the smallest and most
informal one, gets benefits from having a A Glossary is an often informal list of terms
vision and a release plan. and definitions. It defines a common
language, the minimal basis for mutual
Every project, but the most informal ones, understanding in a project.
needs some form of Software A Data Dictionary is a structured repository
requirements specification, in order to of data definitions, which specifies
document the shared understandings structures and relationships of data.
between client and developers. Depending
on needs and preferences, the software Who, when and how (to use the
requirements specification may be more or template)
less formal, and it may contain every detail
or just the most significant points of In the tradition of software development,
agreement. the role which has the responsibility to
document requirements is called “analyst”.
The most common elements that constitute In actual organizational contexts and
a software requirements specification are: situations, this role may be fulfilled by
1. A set of user stories, or use cases. people with different labels.
User stories are small chunks of
system functionality; use cases are The timing of the specification depends on
more complete operational the software development process used.
scenarios of system usage. User Old “waterfall” methods require the
stories are short, and may specification of all detailed requirements
correspond to a single atomic upfront, and a global client validation (client
functional requirement (see below) ; signature) before development begins.
use cases may be longer because
they describe end-to-end usage Iterative and agile methods suggest a just-
scenarios. in-time approach to requirements
2. A list of atomic requirements (“the management. Partial sets of requirements

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 3/13

(say, those concerning a specific system just-in-time requirements definition works

functionality) are detailed just before their effectively for functional requirements, it
implementation, in order to make as short may be dangerous for non functional
as possible the cycle of definition-build- requirements, because a late discovery of
test, and to reduce the risks and the a non functional requirement (say, related
impacts of misunderstandings and reworks. to internationalization, or portability, or
In these contemporary approaches, the security) may cause extensive rework.
software requirements specification may be When it is possible, it is far better to clarify
created and validated incrementally. It is a non functional requirements at the
growing mosaic, not a monolith. beginning of a project.

But all requirements are not equal. While

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 4/13

System <_________>

Requirements
Version History
Version n. Date Author Changes

Index
Purpose and audience for this document..............................................................................6
Vision .....................................................................................................................................7
System background...........................................................................................................7
Business Context, Opportunities and Risks.................................................................7
Stakeholders Profiles and Needs.................................................................................7
Main Characteristics of the System...................................................................................7
Goals of the System.....................................................................................................7
System Context: relationships with users and external systems.................................7
Major Features.............................................................................................................8
Dependencies and Critical Success Factors................................................................8
Release Plan .........................................................................................................................9
Requirements Specification ................................................................................................10
Use Cases / User Stories................................................................................................10
Atomic Requirements......................................................................................................10
Functionality.....................................................................................................................11
Detailed Functional Requirement................................................................................11
Data and Accuracy Requirements...............................................................................11
Interoperability.............................................................................................................11
Responsibility..............................................................................................................11
Operativeness..................................................................................................................11
Availability....................................................................................................................11
Performance................................................................................................................11
Capacity.......................................................................................................................11
Scalability.....................................................................................................................11
Reliability.....................................................................................................................11
Installation....................................................................................................................11
Portability ....................................................................................................................11
Compliance......................................................................................................................11
Laws and Regulations.................................................................................................11

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 5/13

External and Internal Standards..................................................................................11

Audit.............................................................................................................................11
Business Rules............................................................................................................11
Technologies...............................................................................................................11
Cultural and Political Requirements............................................................................11
Usability...........................................................................................................................11
Physical Environment..................................................................................................12
Appearance and Style.................................................................................................12
Ease of Use.................................................................................................................12
Personalization............................................................................................................12
Internationalization......................................................................................................12
Learning Time..............................................................................................................12
Accessibility.................................................................................................................12
Safety and Security..........................................................................................................12
Safety...........................................................................................................................12
Access Protection........................................................................................................12
Integrity........................................................................................................................12
Privacy.........................................................................................................................12
Project Time Requirements.............................................................................................12
Project Budget Requirements..........................................................................................12
Documentation, Maintenance and Support.....................................................................12
Documentation............................................................................................................12
Maintenance................................................................................................................12
Support........................................................................................................................12
Training........................................................................................................................12
Glossary - Data Dictionary...................................................................................................13

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 6/13

Purpose and audience for this document

Purpose
State the purpose of this document (e.g. "Document the software requirements for Project
YYY"). When useful, describe briefly what's included in the document.

Audience
State the intended audience for this document (e.g. "This document is targeted to anyone
involved in the project, and in particular to the following roles...").

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 7/13

Vision

The Vision is a high level system specification. In its simplest form, it may be a two-pages
product data sheet. In its most complex form, it may be a 20 pages executive-level system
description.
It is the main communication medium about the work to be done. It contains no details.

System background

Business Context, Opportunities and Risks

Explain the business reasons and the origin for this system.

Stakeholders Profiles and Needs

List the stakeholders for this system. The scheme of the following example may be used:

Stakeholder Why is involved Interests and Needs

Marketing Project client Competitive advantage
Fast project completion
Cost control
Seller System user Speed and usability
Estimate simulation features
Legal Legal implications Compliance with international laws
department

Main Characteristics of the System

Goals of the System

Describe briefly the goal of the system from the point of view of the client.

System Context: relationships with users and external systems

Describe synthetically the system context, that is the relationships of this system with
users and external systems.
The system context draws the boundary that distinguishes what's in the system and what's
outside of it. The context also represents the relationships between the system and the
external entities with which the system interacts.

For complex systems there may be up to 3 different levels of context, specifying the
by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License
 Requirements Document Pag. 8/13

boundaries for the system at different levels:

0. Socio-technical level.
At this level, a system may be made of human, hardware and software
components. It is a business level, which includes both the aspects (activities,
communications) to be automated, and those that will not be automated. It is a very
useful analysis level, because it may help to discover opportunities and risks of
automation. The socio-technical level may be omitted when the projects is a minor
evolution of an existing system, or if the boundaries of the physical and software
levels are already defined.
2. Physical level.
At this level, a system may be made of hardware and software components, but not
of human components. Every human activity is outside the system. It is a useful
level for systems in which the hardware components must be built, because they
are not standard (e.g. medical apparels, car alarm systems). It is not useful to
describe it with a separate context level for software systems which will run on
standard hardware.
3. Software level.
At this level, a system may be made only of software components . Everything that
is not software is outside the system. Often, this is the only level that needs to be
described.

If there are a lot of different user roles and external systems, simplify with abstractions.
The detailed requirements for the relationships of the system with the external world are
better expressed in the Requirements Specification than in the Vision.

The system context may be expressed in graphical form, with a UML (Unified Modeling
Language) diagram simple as the following one:

«e x t e sr ny sa t l e m »
A u t h e n t i c a t i o n
« s y s t e m »

E -C o m m e r c e
C u s t o m e r
«e x t e sr ny sa t l e m »
P a y m e n t

Major Features
List the major features of the product, that is the most relevant functions and
characteristics (operating environment, level of service, usability, security ecc.).

Dependencies and Critical Success Factors

Describe which factors may influence the quality and the success of the product, such as
the availability of an external component in a certain date.

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 9/13

Release Plan

The release plan documents, at a high level, the release milestones shared between client
and developers. It specifies the progression of releases and their content. Whenever the
agreements between client and developers should change, the release plan must be
changed accordingly.

The intent of the release plan is to clarify our forecasts about the incremental delivery of
system functions, because in most projects not every requirement are satisfied at the
same time. The release plan is a road map, not a detailed work plan.

The level of detail of the release plan must be coherent with the vision and the
requirements specification. For example, if the Requirements specification is organized
around use cases, it is useful that the release plan references them.

Example
Feature or use case 1st release (date) 2nd release (date) 3rd release (date)
UC1 x (partial, only base *
scenario)
UC2 *
UC3 * (partial, without *
alternate scenarios 2
and 3)
UC4 x
UC5 * (partial) *
UC6 *
UC7 x

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 10/13

Requirements Specification

The requirements specification contains details. It has two main Parts: Use Cases AND
Atomic Requirements.

Use Cases / User Stories

This section is organized around user functionalities. I suggest the use of an existing
template, such as the one provided by Alistair Cockburn -
http://alistair.cockburn.us/index.php/Basic_use_case_template, or a similar one.

Atomic Requirements

The following sections contain a list of atomic requirements, organized upon a

classification scheme such as the one used in the guide Requirements-By-Example,
http://www.analisi-disegno.com/requisiti/Requirements-By-Example.htm, used below, or a
similar one.

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 11/13

Functionality

Detailed Functional Requirement

Data and Accuracy Requirements

Interoperability

Responsibility

Operativeness

Availability

Performance

Capacity

Scalability

Reliability

Installation

Portability

Compliance

Laws and Regulations

External and Internal Standards

Audit

Business Rules

Technologies

Cultural and Political Requirements

Usability

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 12/13

Physical Environment

Appearance and Style

Ease of Use

Personalization

Internationalization

Learning Time

Accessibility

Safety and Security

Safety

Access Protection

Integrity

Privacy

Project Time Requirements

Project Budget Requirements

Documentation, Maintenance and Support

Documentation

Maintenance

Support

Training

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License

 Requirements Document Pag. 13/13

Glossary - Data Dictionary

The Glossary - Data Dictionary section deals with informations and data. It may be
specified at different complexity levels, depending on actual needs.

A Glossary is an often informal list of terms and definitions. It defines a common language,
the minimal basis for mutual understanding in a project. It is highly recommended.
A Data Dictionary is a structured repository of data definitions, which specifies structures
and relationships of data.

A Data Dictionary is extremely useful as a complement to software requirements in

complex projects.

For the requirements documentation of simpler projects, a Glossary may be sufficient. A

good example of Glossary is the Human Genome Glossary:
http://www.ornl.gov/sci/techresources/Human_Genome/glossary/

by Adriano Comai – www.analisi-disegno.com – Creative Commons Attribution-Non-commercial 3.0 Unported License