5.1 Documentprograms for a computer application that accesses a database using SQL.
The documents associatedwith a software project and the system being developed have a number of associatedrequirements: 1. They should act as a communication medium between members of the developmentteam. 2. They should be a system informationrepository to be used bymaintenance 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.
Product documentationProduct documentation is concerned with describing the delivered softwareproduct. Unlike most process documentation, it has a relativelylong life. It must evolve in step with the product which it describes.Product documentation includesuser documentation which tells users how to use the software productand system documentation which is principally intended for maintenanceengineers.User DocumentationUsers of a system are not all the same. The producer of documentation must structureit to cater for different user tasks and different levels of expertise and experience.
It is particularly important to distinguish between end-users andsystem administrators: 1. End-usersuse 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 anetwork of workstations or as a technicalguru who fixes end-userssoftware problems and who liaises between users and the software supplier. To cater for these different classesof userand differentlevels of user expertise, there are at least 5 documents(or perhapschapters in a single document) whichshould be delivered with the software system (Figure1). The functionaldescription of the system outlines the system requirements and briefly describesthe services provided. This document should provide anoverview of the system. Users should be able to read this documentwith 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 thefilesmaking 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 fileswhich 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 meantthat some supplierssee this document as unnecessary. In fact, it is still requiredto help system managers discover and fix problems with the installation.
The introductory manual should present an informal introduction to the system, describingits ‘normal’ usage. It should describehow to get started and how end-usersmight make use of the common system facilities. It should be liberallyillustrated with examples. Inevitably beginners, whatever theirbackground and experience, will make mistakes. Easily discoveredinformation 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. For example,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 spendingtime in consultation of manuals although should not be seen as a replacement for more comprehensive documentation System DocumentationSystem documentation includes all of the documents describing the system itself from the requirements specification to the final acceptance test plan. Documents describingthe 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 overviewsleading the reader into more formal and detailed descriptions of each aspect of the system. For large systems that are developedto a customer’sspecification, 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 descriptionof its functionalityand interfaces. 5. Program source code listings. These should be commented where the comments should explain complex sections of code and provide arationale 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 informationis now normally maintained electronically rather than on paper with selected informationprinted on demand from readers. 6.
Validation documents describing how each program is validated and how the validationinformation relates to the requirements. 7. A system maintenance guide which describes known problems with thesystem, 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.