Software Documentation

[attachment=18334]
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.
The documents associated with a software project and the system being
developed have a number of associated requirements:
1. They should act as a communication medium between members of the
development team.
2. They should be a system information repository to be used by
maintenance engineers.
3. They should provide information for management to help them plan,
budget and schedule the software development process.
4. Some of the documents should tell users how to use and administer the
system.
Satisfying these requirements requires different types of document from
informal working documents through to professionally produced user manuals.
Software engineers are usually responsible for producing most of this
documentation although professional technical writers may assist with the final
polishing of externally released information.



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 two
classes:
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 is produced so that the development of the system can
be managed. Product documentation is used after the system is operational but
is also essential for management of the system development. The creation of
a document, such as a system specification, may represent an important
milestone in the software development process.

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.