19-11-2012, 06:02 PM
Software Documentation
[attachment=40260]
Introduction
All large software development projects, irrespective of application, generate a
large amount of associated documentation. For moderately sized systems, the
documentation will probably fill several filing cabinets; for large systems, it
may fill several rooms. A high proportion of software process costs is incurred
in producing this documentation. Furthermore, documentation errors and
omissions can lead to errors by end-users and consequent system failures with
their associated costs and disruption. Therefore, managers and software
engineers should pay as much attention to documentation and its associated
costs as to the development of the software itself.
Process and Product Documentation
For large software projects, it is usually the case that documentation starts
being generated well before the development process begins. A proposal to
develop the system may be produced in response to a request for tenders by an
external client or in response to other business strategy documents. For some
types of system, a comprehensive requirements document may be produced
which defines the features required and expected behavior of the system. During
the development process itself, all sorts of different documents may be
produced – project plans, design specifications, test plans etc.
It is not possible to define a specific document set that is required – this
depends on the contract with the client for the system, the type of system
being developed and its expected lifetime, the culture and size of the company
developing the system and the development schedule that it expected.
However, we can generally say that the documentation produced falls into twoclasses:
1. Process documentation These documents record the process of
development and maintenance. Plans, schedules, process quality
documents and organizational and project standards are process
documentation.
2. Product documentation This documentation describes the product
that is being developed. System documentation describes the product
from the point of view of the engineers developing and maintaining the
system; user documentation provides a product description that is
oriented towards system users.
Process documentation
Effective management requires the process being managed to be visible.
Because software is intangible and the software process involves apparently
similar cognitive tasks rather than obviously different physical tasks, the only
way this visibility can be achieved is through the use of process documentation.
Process documentation falls into a number of categories:
1. Plans, estimates and schedules These are documents produced by
managers which are used to predict and to control the software process.
2. Reports These are documents which report how resources were used
during the process of development.
3. Standards These are documents which set out how the process is to be
implemented. These may be developed from organizational, national or
international standards.
Product documentation
Product documentation is concerned with describing the delivered software
product. Unlike most process documentation, it has a relatively long life. It
must evolve in step with the product which it describes. Product documentation
includes user documentation which tells users how to use the software product
and system documentation which is principally intended for maintenance
engineers.
User Documentation
Users of a system are not all the same. The producer of documentation must
structure it to cater for different user tasks and different levels of expertise and
experience. It is particularly important to distinguish between end-users and
system administrators:
1. End-users use the software to assist with some task. This may be flying
an aircraft, managing insurance policies, writing a book, etc. They
want to know how the software can help them. They are not interested
in computer or administration details.
System Documentation
System documentation includes all of the documents describing the system
itself from the requirements specification to the final acceptance test plan.
Documents describing the design, implementation and testing of a system are
essential if the program is to be understood and maintained. Like user
documentation, it is important that system documentation is structured, with
overviews leading the reader into more formal and detailed descriptions of each
aspect of the system.
[attachment=40260]
Introduction
All large software development projects, irrespective of application, generate a
large amount of associated documentation. For moderately sized systems, the
documentation will probably fill several filing cabinets; for large systems, it
may fill several rooms. A high proportion of software process costs is incurred
in producing this documentation. Furthermore, documentation errors and
omissions can lead to errors by end-users and consequent system failures with
their associated costs and disruption. Therefore, managers and software
engineers should pay as much attention to documentation and its associated
costs as to the development of the software itself.
Process and Product Documentation
For large software projects, it is usually the case that documentation starts
being generated well before the development process begins. A proposal to
develop the system may be produced in response to a request for tenders by an
external client or in response to other business strategy documents. For some
types of system, a comprehensive requirements document may be produced
which defines the features required and expected behavior of the system. During
the development process itself, all sorts of different documents may be
produced – project plans, design specifications, test plans etc.
It is not possible to define a specific document set that is required – this
depends on the contract with the client for the system, the type of system
being developed and its expected lifetime, the culture and size of the company
developing the system and the development schedule that it expected.
However, we can generally say that the documentation produced falls into twoclasses:
1. Process documentation These documents record the process of
development and maintenance. Plans, schedules, process quality
documents and organizational and project standards are process
documentation.
2. Product documentation This documentation describes the product
that is being developed. System documentation describes the product
from the point of view of the engineers developing and maintaining the
system; user documentation provides a product description that is
oriented towards system users.
Process documentation
Effective management requires the process being managed to be visible.
Because software is intangible and the software process involves apparently
similar cognitive tasks rather than obviously different physical tasks, the only
way this visibility can be achieved is through the use of process documentation.
Process documentation falls into a number of categories:
1. Plans, estimates and schedules These are documents produced by
managers which are used to predict and to control the software process.
2. Reports These are documents which report how resources were used
during the process of development.
3. Standards These are documents which set out how the process is to be
implemented. These may be developed from organizational, national or
international standards.
Product documentation
Product documentation is concerned with describing the delivered software
product. Unlike most process documentation, it has a relatively long life. It
must evolve in step with the product which it describes. Product documentation
includes user documentation which tells users how to use the software product
and system documentation which is principally intended for maintenance
engineers.
User Documentation
Users of a system are not all the same. The producer of documentation must
structure it to cater for different user tasks and different levels of expertise and
experience. It is particularly important to distinguish between end-users and
system administrators:
1. End-users use the software to assist with some task. This may be flying
an aircraft, managing insurance policies, writing a book, etc. They
want to know how the software can help them. They are not interested
in computer or administration details.
System Documentation
System documentation includes all of the documents describing the system
itself from the requirements specification to the final acceptance test plan.
Documents describing the design, implementation and testing of a system are
essential if the program is to be understood and maintained. Like user
documentation, it is important that system documentation is structured, with
overviews leading the reader into more formal and detailed descriptions of each
aspect of the system.