programs for a computer application that accesses a database using SQL.
The documents associated
with a software project and the system being developed have a number of associated
1. They should act as a communication medium between members of the development
2. They should be a system information
repository to be used by
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.
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
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
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.
2. System administrators are responsible for managing the software used by end-users.
This may involve acting as an operator if the system is a large mainframe system, as a network manager is the system involves a
network of workstations or as a technical
guru who fixes end-users
software problems and who liaises between users and the software supplier.
To cater for these different classes
levels of user expertise, there are at least 5 documents
chapters in a single document) which
should be delivered with the software system (Figure1).
description of the system outlines the system requirements and briefly describes
the services provided. This document should provide an
overview of the system. Users should be able to read this document
with an introductory manual and decide if the system is what they need.
The system installation document is intended for system administrators. It should provide details of how to install the system in a particular environment.
It should contain a description of the
making up the system and the minimal hardware configuration required. The permanent files which must be established, how to start the system and the configuration dependent files
which must be changed to tailor the system to a particular host system should also be described.
The use of automated installers for PC software has meant
that some suppliers
see this document as unnecessary. In fact, it is still required
to help system managers discover and fix problems with the installation.
The introductory manual should present an informal introduction to the system, describing
its ‘normal’ usage.
It should describe
how to get started and how end-users
might make use of the common system facilities. It should be liberally
illustrated with examples. Inevitably beginners, whatever their
background and experience, will make mistakes.
information on how to recover from these mistakes and restart useful work should be an integral part of this document.
A more general system administrator’s guide should be provided for some types of system such as command and control systems. This should describe the messages generated when the system interacts with other systems and how to react to these messages.
If system hardware is involved, it might also explain the operator’s task in maintaining that hardware.
it might describe how to clear faults in the system console, how to connect new peripherals, etc.
As well as manuals,
other, easy-to-use documentation might be provided. A quick reference card listing available system facilities and how to use them is particularly convenient for experienced system users.
On-line help systems, which contain brief information about the system, can save the user spending
time in consultation of manuals although should not be seen as a replacement for more comprehensive 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.
For large systems that are developed
to a customer’s
specification, the system documentation should include:
1. The requirements document and an associated rationale.
2. A document describing the system architecture.
3. For each program in the system, a description of the architecture of that program.
4. For each component in the system, a description
of its functionality
5. Program source code listings. These should be commented where the comments should explain complex sections of code and provide a
rationale for the coding method used. If meaningful names are used and a good, structured programming style is used, much of the code should be self-documenting without the need for additional comments. This information
is now normally maintained electronically rather than on paper with selected information
printed on demand from readers.
6. Validation documents describing how each program is validated and how the validation
information relates to the requirements.
7. A system maintenance guide which describes known problems with the
system, describes which parts of the system are hardware and software dependent and which describes how evolution of the system has been taken into account in its design.