Systems documentation

consideration
Introduction
 Software engineering projects, as defined by the IEEE/EIA, consist of a
number of development activities
 Each activity is characterized by a set of deliverables, normally in the
form of code or documentation.
 Providing a structured template for software documentation assists both
the customers and developers as well as the assessment aspects of a
software engineering project.
 These templates provide a guide to the expected format and content of
the documentation deliverables based on international standards.
 This presentation does not provide specific assessment criteria: it
describes the development documentation.
 Also, it does not cover the product documentation (user manual,
reference manual, installation manual, or internal documentation).
Contd..
The minimal document set, and the content of each
document, has been derived from the full IEEE set of
software engineering documents.

The templates described here are based on the most recent

IEEE standards and US MIL-STD-498
Various System Documentations
Various types of Documentation Description
used

Software Project Management Description of the software approach and

Plan (SPMP) associated milestones.

Software Requirements Description of the expected software

Specifications (SRS) features, constraints, interfaces and
other attributes.

Software Design Description (SDD) Description of how the software will meet
the requirements. Also describes the
rationale for design decisions taken.

Software Test Documentation Description of the plan and specifications

(STD) to verify and validate the software and the
results.
Purpose of each document
Types of Documentation Summary of Purpose

Software Project Management Plan To document the agreed deliverables

(SPMP) and dates.

Software Requirements Specifications To document the agreed requirements

(SRS) with the project supervisor; to provide
the basis for design; to provide the basis
for system test.
Software Design Description (SDD) To document the design and design
decisions in order to provide the
basis for implementation and unit test

Software Test Documentation (STD) To document how the software will be

tested, and record the results.
Common Sections for the Documentation Set.
 Each document within the recommended set has some common
characteristics. The following pages are included in each document:
 I. Cover page (contents & layout)
Contd..
II. Additional Material (contents)
ADDITIONAL ISSUES
DEFINITIONS, ACRONYMS, AND ABBREVIATIONS
REFERENCES
APPENDICES
Contents of the Documentation Set.
Contd..
Contd..
Contd..
Requirements Analysis and
Requirements Specification
Requirements Engineering

Requirements Engineering

Requirements Elicitation Requirements Analysis

Requirements Specification Requirements Verification

Requirements Management
Requirements Analysis and
Specification definitions
Requirements Analysis is the process of
understanding the customer needs and expectations
from a proposed system or application and is a well-
defined stage in the Software Development Life Cycle
model.
Requirements are a description of how a system
should behave or a description of system properties or
attributes. It can alternatively be a statement of ‘what’
an application is expected to do.
What vs. How Dilemma3
User
UserNeeds
Needs
What
How
System
System
Requirements What
Requirements
How

System
SystemDesign
Design What
How
Software
Software
Requirements
Requirements What
How
Software
Software
Design
Design
Requirements vs. Design
Requirements Design

Describe what will be delivered Describe how it will be done

Primary goal of analysis: Primary goal of design:

UNDERSTANDING OPTIMIZATION
There is more than one solution There is only one (final) solution

Customer interested Customer not interested (Most of

the time) except for external
Requirement Specification
Requirements Specification
A document that clearly and precisely describes, each of
the essential requirements of the software and the
external interfaces.
 (functions, performance, design constraint, and quality
attributes)
Each requirement is defined in such a way that its
achievement is capable of being objectively verified by a
prescribed method; for example inspection,
demonstration, analysis, or test
Contd..
Requirements, once elicited, modeled and analyzed should be documented
in clear, unambiguous terms.
A written requirements document is critical so that its circulation is
possible among all stakeholders including the client, user-groups, the
development and testing teams.
Current requirements engineering practices reveal that a well-designed,
clearly documented Requirements Specification is vital and serves as a:
 Base for validating the stated requirements and resolving stakeholder
conflicts, if any
 Contract between the client and development team
 Basis for systems design for the development team
 Bench-mark for project managers for planning project development
lifecycle and goals
 Source for formulating test plans for QA and testing teams
 Resource for requirements management and requirements tracing
 Basis for evolving requirements over the project life span
Contd..
The software requirements specification is a document that lists
out stakeholders’ needs and communicates these to the technical
community that will design and build the system.
The challenge of a well-written requirements specification is to
clearly communicate to both these groups and all the sub-groups
within.
To overcome this, Requirements Specifications may be
documented separately as
User Requirements - written in clear, precise language with
plain text and use cases, for the benefit of the customer and
end-user
System Requirements - expressed as a programming or
mathematical model, addressing the Application Development
Team and QA and Testing Team.
Requirements Specification serves as a starting point for software,
hardware and database design. It describes the functions of the
The requirements document
The requirements document is the official statement
of what is required of the system developers.
Should include both a definition of user requirements
and a specification of the system requirements.
It is NOT a design document. As far as possible, it
should set of WHAT the system should do rather than
HOW it should do it
Users of a requirements document
Specify the requirements and
read them to check that they
System
customers meet their needs. T hey
specify changes to the
requirements

Use the requirements

document to plan a bid for
Managers
the system and to plan the
system development process

System Use the requirements to

engineers understand what system is to
be developed

System test Use the requirements to

engineers develop validation tests for
the system

System Use the requirements to help

maintenance understand the system and
eng ineers the relationships between its
par ts
IEEE Standards for Various
Documentations
IEEE Standard Description

IEEE 830-1998 Specification of software requirements

IEEE 730 SQAP - Software Quality Assurance Plan 

IEEE 828 SCMP - Software Configuration Management Plan

IEEE 829 STD - Software Test Documentation 

IEEE 830 SRS - Software Requirements Specification 

IEEE 1012 SVVP - Software Validation & Verification Plan

IEEE 1016 SDD - Software Design Description

IEEE 1058 SPMP - Software Project Management Plan

IEEE requirements standard
Defines a generic structure for a requirements document
that must be instantiated for each specific system.
Introduction.
General description.
Specific requirements.
Appendices.
Index.
Requirements document structure
Preface
Introduction
Glossary
User requirements definition
System architecture
System requirements specification
System models
System evolution
Appendices
Index
Key points
Requirements set out what the system should do and
define constraints on its operation and implementation.
Functional requirements set out services the system
should provide.
Non-functional requirements constrain the system
being developed or the development process.
User requirements are high-level statements of what
the system should do. User requirements should be
written using natural language, tables and diagrams.
Key points
System requirements are intended to communicate
the functions that the system should provide.
A software requirements document is an agreed
statement of the system requirements.
The IEEE standard is a useful starting point for
defining more detailed specific requirements
standards.
Difference Between URS and SRS
SRS is system requirement specification which
usually contains functional requirements. URS is
user requirement specification which contains
business requirements.

URS document is drafted by the clients (end

users) in their own language. This URS document
is converted into SRS document by the system
analysts of s/w development company in the
language understandable by their team
Example
A bank wants to computerize their bank branches. They
approach a s/w development company with a URS.

One of the requirements defined by the end users in URS is to

calculate new balance each time customer deposits or
withdraws money in his/her bank a/c. So, the new balance will
be equal to old balance plus total deposits, less total
withdrawals.

Now, the system analysts look into this and define the same
point as, 

Balance = Balance + TotalDeposit

Balance = Balance – TotalWithdrawals
User Requirement Specification (URS)
User Requirements Specifications (URS)
are prepared for each critical utility or piece
of equipment prior to the manufacturing
stage.

The specification provides a list of

requirements for the planned system. The
User Requirements Specification specifies
the needs of the end user as well as any
regulatory requirements.
Contd…

The document is provided to the supplier in

order to ensure that all expected requirements, of
the end user, for the utility or piece of equipment
have been specified and supplied prior to the
actual manufacturing stage.

These specifications will be the basis for the

Functional Requirements Specification and the
Hardware and Software Specifications that detail
the design of the utility or piece of equipment.
Contd..
A good set of user requirements are needed for
any project, especially computer system
projects, to be successful.

This is where many projects fail, in that they

do not specify correctly what the system
should do.

In fact many systems have just been given a

deadline for delivery, a budget to spend, and a
Guidelines for URS
1. Each requirement must be uniquely referenced,
although not mandatory, attempts at this stage should be
made to keep each requirement to less than 200 words.

2. Requirement statements should not be duplicated or

contradicted.

3. The URS should express requirements and not design

solutions.

4. Each requirement should be testable.

Contd..
5. The user requirement specifications must be
understood by both the customer and supplier;
ambiguity and jargon must be avoided.

6. Whenever possible, the user requirement

specifications must distinguish between regulatory
requirements and desirable features, by using should
to represent a nice to have function, and must to
indicate a mandatory function.

7. There should be a formal review of the URS between

the customer and supplier to ensure that requirements
URS SCOPE
User Requirements Specification (URS) Scope includes
but is not limited to;
* Level-1, full details of end user operability.
* Level-2, full details of functionality.
* Level-3, software functionality interface.
* A full description of the required system performance.
* Performance criteria, critical parameters and operating
range.
* Cleaning and maintenance requirements.
* Appropriate regulatory requirements.
* Documentation requirements.
* Training requirements.
* Industry standard testing may be required.
Software Requirement Specifications
(SRS)
A Software Requirements
Specification (SRS) - a requirements
specification for a software system - is a
complete description of the behavior of a
system to be developed.

It establishes the basis for agreement between

customers and contractors or suppliers on what
the software product is expected to do, as well
as what it is not expected to do.
Features of SRS
Some of the features of SRS are -
• It sets permits a rigorous assessment of
requirements before design can begin.
• It sets the basis for software design, test,
deployment, training etc. It also sets pre-requisite
for a good design though it is not enough.
• It sets basis for software enhancement and
maintenance.
• It sets Basis for Project plans like Scheduling and
Estimation.
Benefits of a Great SRS
 The IEEE 830 standard defines the benefits of a good SRS:
 Establish the basis for agreement between the customers and the
suppliers on what the software product is to do. The complete
description of the functions to be performed by the software
specified in the SRS will assist the potential users to determine if the
software specified meets their needs or how the software must be
modified to meet their needs.
 Reduce the development effort. The preparation of the SRS forces
the various concerned groups in the customer’s organization to
consider rigorously all of the requirements before design begins and
reduces later redesign, recoding, and retesting. Careful review of the
requirements in the SRS can reveal omissions, misunderstandings,
and inconsistencies early in the development cycle when these
problems are easier to correct.
 Provide a basis for estimating costs and schedules. The description
of the product to be developed as given in the SRS is a realistic basis
Contd..
Provide a baseline for validation and verification. Organizations can
develop their validation and Verification plans much more productively
from a good SRS. As a part of the development contract, the SRS
provides a baseline against which compliance can be measured.

Facilitate transfer. The SRS makes it easier to transfer the software

product to new users or new machines. Customers thus find it easier to
transfer the software to other parts of their organization, and suppliers
find it easier to transfer it to new customers.

Serve as a basis for enhancement. Because the SRS discusses the

product but not the project that developed it, the SRS serves as a basis
for later enhancement of the finished product. The SRS may need to be
altered, but it does provide a foundation for continued production
evaluation.
What should SRS Address ?
 From the IEEE 830 standard:
The basic issues that the SRS writer(s) shall address are the
following:
 a) Functionality. What is the software supposed to do?
 b) External interfaces. How does the software interact with people,
the system’s hardware, other hardware, and other software?
 c) Performance. What is the speed, availability, response time,
recovery time of various software functions, etc.?
 d) Attributes. What are the portability, correctness, maintainability,
security, etc. considerations?
 e) Design constraints imposed on an implementation. Are there
any required standards in effect, implementation language, policies
for database integrity, resource limits, operating environment(s) etc.? 
Characteristics of a great SRS
 From the IEEE 830 standard:
An SRS should be
a) Correct
b) Unambiguous
c) Complete
d) Consistent
e) Ranked for importance and/or stability
f) Verifiable
g) Modifiable
h) Traceable
Contd..
Correct - The specifications prepared is to be correct. No one
writes a specification that they know is incorrect. We like to say
- "Correct and Ever Correcting." The discipline is keeping the
specification up to date when you find things that are not correct.
Unambiguous - An SRS is unambiguous if, and only if, every
requirement stated therein has only one interpretation. Again,
easier said than done. Spending time on this area prior to
releasing the SRS can be a waste of time. But as you find
ambiguities - fix them.
Complete - A simple judge of this is that is should be all that is
needed by the software designers to create the software.
Consistent - The SRS should be consistent within itself and
consistent to its reference documents. If you call an input "Start
and Stop" in one place, don't call it "Start/Stop" in another.
Contd..
Ranked for Importance - Very often a new system has
requirements that are really marketing wish lists. Some may not
be achievable. It is useful provide this information in the SRS.
Verifiable - Don't put in requirements like - "It should provide
the user a fast response." Another of my favorites is - "The
system should never crash." Instead, provide a quantitative
requirement like: "Every key stroke should provide a user
response within 100 milliseconds."
Modifiable - Having the same requirement in more than one
place may not be wrong - but tends to make the document not
maintainable.
Traceable - Often, this is not important in a non-politicized
environment. Why do we need this requirement?
Requirements Analysis Issues
Stakeholder issues
 Users do not understand what they want or users don't have a clear idea
of their requirements
 Users will not commit to a set of written requirements
 Users insist on new requirements after the cost and schedule have been
fixed
 Communication with users is slow
 Users often do not participate in reviews or are incapable of doing so
 Users are technically unsophisticated
 Users do not understand the development process
 Users do not know about present technology
This may lead to the situation where user requirements keep
changing even when system or product development has been
started.
Contd..
Engineer/developer issues
Possible problems caused by engineers and developers
during requirements analysis are:
 Technical personnel and end-users may have different
vocabularies. Consequently, they may wrongly believe they
are in perfect agreement until the finished product is supplied.
 Engineers and developers may try to make the requirements
fit an existing system or model, rather than develop a system
specific to the needs of the client.
 Analysis may often be carried out by engineers or
programmers, rather than personnel with the people skills and
the domain knowledge to understand a client's needs properly.