Introduction to
Systems Development
UNIT 4 INTRODUCTION TO
DOCUMENTATION OF SYSTEMS
Structure Page No.
4.0 Introduction 46
4.1 Objectives 46
4.2 Concepts and Process of Documentation 46
4.3 Types of Documentation 49
4.3.1 System Requirements Specification
4.3.2 System Design Specification
4.3.3 Test Design Document
4.3.4 User Manual
4.4 Different Standards for Documentation 58
4.5 Documentation and Quality of Software 60
4.6 Good Practices for Documentation 60
4.7 Summary 61
4.8 Solutions/ Answers 61
4.9 Further Readings 61
4.0 INTRODUCTION
Documentation is a process to help users of software and other people to use and
interact with system. Effective and accurate documentation is very necessary for the
success of any system. Documentation becomes part of each step of system
development through out the process of system development even before the
documentation starts officially. During the process of system development, study
reports and other necessary information are documented to help people involved in
system development to understand the process. There are many kinds of
documentation namely analysis documentation, design documentation, interface
documentation, internal program documentation and user-oriented documentation.
Documentation should not be seen as a overhead for system development. Rather,
documentation has to be seen as an investment for the development of high quality
software.
4.1 OBJECTIVES
After going through this unit, you should be able to:
• understand the concept of documentation;
• understand the importance of documentation;
• learn about various documents and process of documentation;
• understand application of various standards of documentation processes;
• differentiate between various documentation processes;
• know relation between the documentation and quality of software; and
• understand the good practices for documentation process.
4.2 CONCEPTS AND PROCESS OF
DOCUMENTATION
Documentation may be defined as the process of communicating about the system.
The person who is responsible for this communication is called documenter. It may be
46
, Introduction to
noted that documenter is not responsible for the accuracy of the information, and his Documentation of
job is just to communicate or transfer the information. Systems
The ISO standard ISO/IEC 12207:1995 describes documentation “as a supporting
activity to record information produced by a system development life cycle process.”
Why documentation?
Documentation is needed because it is
• a means for transfer of knowledge and details about description of the system
• to communicate among different teams of the software project;
• to help corporate audits and other requirements of the organization;
• to meet regulatory demand;
• needed for IT infrastructure management and maintenance; and
• needed for migration to a new software platform.
Document communicates the details about the system targeted at different audience. It
explains the system. The ever-increasing complexity of information system requires
emphasis on well-established system of documentation. Every information system
should be delivered along with an accurate and understandable document to those who
will use the software.
Traditionally, documentation was done after the development of the software is
completed. However, as the software development process is becoming complex and
involved, documentation has become an integral part of each system development
process. Documentation is now carried out at every stage as a part of development
process. We will also discuss how documentation affects quality of the software later
in this section.
When the process of documentation is undertaken as a separate process, it requires
planning in its own right. The figure below shows, how at the development process,
documentation is done alongside each step. Design and development activities of
software depend on a certain base document. Documentation is to be carried out
before actually implementing the design. In such a case, any flaw in design identified
can be changed in the document thereby saving cost and time during implementation.
If documentation is being developed for an existing software, then documentation is
done along side the software development process.
The Process of Documentation
The following are various steps involved in the process of documentation:
Collection of source material: The very first step of any documentation process is to
acquire the required source material for preparation of document. The material is
collected including specifications, formats, screen layouts and report layouts. A copy
of the operational software is helpful for preparing the documentation for user.
Documentation Plan: The documenter is responsible for preparation of a
documentation plan, which specifies the details of the work to be carried out to
prepare the document. It also defines and the target audience.
Review of Plan: The plan as set out in the process above is reviewed to see that
material acquired is correct and complete.
Creation of Document: The document is prepared with the help of document
generator.
47
, Introduction to
Systems Development
Testing of Document: The document created is tested for usability as required by the
target audience.
Maintain Document: Once the document is created and distributed, it must be kept up
to date with new version of the software product. It must be ensured that the latest
document is available to the user of the software.
Figure 4.1 depicts various stages of the process of documentation.
Acquire source
material for
documentation
Planning
documentation
Review
documentation plan
Develop document
as per the plan
Test the usability of
documentation
Reproduce and
distribute document
Maintain the document
Figure 4.1: Stages of process of documentation
Check Your Progress 1
1. ISO standard ISO/IEC 12207:1995 describes documentation as a ____________
activity.
2. The documenter is responsible for preparation of a documentation plan
(Yes/No).
48
Systems Development
UNIT 4 INTRODUCTION TO
DOCUMENTATION OF SYSTEMS
Structure Page No.
4.0 Introduction 46
4.1 Objectives 46
4.2 Concepts and Process of Documentation 46
4.3 Types of Documentation 49
4.3.1 System Requirements Specification
4.3.2 System Design Specification
4.3.3 Test Design Document
4.3.4 User Manual
4.4 Different Standards for Documentation 58
4.5 Documentation and Quality of Software 60
4.6 Good Practices for Documentation 60
4.7 Summary 61
4.8 Solutions/ Answers 61
4.9 Further Readings 61
4.0 INTRODUCTION
Documentation is a process to help users of software and other people to use and
interact with system. Effective and accurate documentation is very necessary for the
success of any system. Documentation becomes part of each step of system
development through out the process of system development even before the
documentation starts officially. During the process of system development, study
reports and other necessary information are documented to help people involved in
system development to understand the process. There are many kinds of
documentation namely analysis documentation, design documentation, interface
documentation, internal program documentation and user-oriented documentation.
Documentation should not be seen as a overhead for system development. Rather,
documentation has to be seen as an investment for the development of high quality
software.
4.1 OBJECTIVES
After going through this unit, you should be able to:
• understand the concept of documentation;
• understand the importance of documentation;
• learn about various documents and process of documentation;
• understand application of various standards of documentation processes;
• differentiate between various documentation processes;
• know relation between the documentation and quality of software; and
• understand the good practices for documentation process.
4.2 CONCEPTS AND PROCESS OF
DOCUMENTATION
Documentation may be defined as the process of communicating about the system.
The person who is responsible for this communication is called documenter. It may be
46
, Introduction to
noted that documenter is not responsible for the accuracy of the information, and his Documentation of
job is just to communicate or transfer the information. Systems
The ISO standard ISO/IEC 12207:1995 describes documentation “as a supporting
activity to record information produced by a system development life cycle process.”
Why documentation?
Documentation is needed because it is
• a means for transfer of knowledge and details about description of the system
• to communicate among different teams of the software project;
• to help corporate audits and other requirements of the organization;
• to meet regulatory demand;
• needed for IT infrastructure management and maintenance; and
• needed for migration to a new software platform.
Document communicates the details about the system targeted at different audience. It
explains the system. The ever-increasing complexity of information system requires
emphasis on well-established system of documentation. Every information system
should be delivered along with an accurate and understandable document to those who
will use the software.
Traditionally, documentation was done after the development of the software is
completed. However, as the software development process is becoming complex and
involved, documentation has become an integral part of each system development
process. Documentation is now carried out at every stage as a part of development
process. We will also discuss how documentation affects quality of the software later
in this section.
When the process of documentation is undertaken as a separate process, it requires
planning in its own right. The figure below shows, how at the development process,
documentation is done alongside each step. Design and development activities of
software depend on a certain base document. Documentation is to be carried out
before actually implementing the design. In such a case, any flaw in design identified
can be changed in the document thereby saving cost and time during implementation.
If documentation is being developed for an existing software, then documentation is
done along side the software development process.
The Process of Documentation
The following are various steps involved in the process of documentation:
Collection of source material: The very first step of any documentation process is to
acquire the required source material for preparation of document. The material is
collected including specifications, formats, screen layouts and report layouts. A copy
of the operational software is helpful for preparing the documentation for user.
Documentation Plan: The documenter is responsible for preparation of a
documentation plan, which specifies the details of the work to be carried out to
prepare the document. It also defines and the target audience.
Review of Plan: The plan as set out in the process above is reviewed to see that
material acquired is correct and complete.
Creation of Document: The document is prepared with the help of document
generator.
47
, Introduction to
Systems Development
Testing of Document: The document created is tested for usability as required by the
target audience.
Maintain Document: Once the document is created and distributed, it must be kept up
to date with new version of the software product. It must be ensured that the latest
document is available to the user of the software.
Figure 4.1 depicts various stages of the process of documentation.
Acquire source
material for
documentation
Planning
documentation
Review
documentation plan
Develop document
as per the plan
Test the usability of
documentation
Reproduce and
distribute document
Maintain the document
Figure 4.1: Stages of process of documentation
Check Your Progress 1
1. ISO standard ISO/IEC 12207:1995 describes documentation as a ____________
activity.
2. The documenter is responsible for preparation of a documentation plan
(Yes/No).
48
