Table of Contents
Introduction 1
Process and Product Documentation 3
Process documentation 3
Product documentation 5
User Documentation 5
System Documentation 7
Document Quality 9
Document structure 9
Documentat
...
Table of Contents
Introduction 1
Process and Product Documentation 3
Process documentation 3
Product documentation 5
User Documentation 5
System Documentation 7
Document Quality 9
Document structure 9
Documentation Standards 12
Process standards 13
Product standards 13
Interchange standards 14
The IEEE standard for user documentation 15
Writing style 16
On-line documentation 18
Document Preparation 19
Figure 4: Word processors and text formatters 21
Figure 5: Document management 22
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.
My goals here are to describe the documentation which may be produced during the software process, to give some hints on ways of writing effective documents and to describe processes involved in producing these documents. I start by discussing different types of documentation that may be produced in a software project. I then cover the important topic of document quality and discuss document structure, documentation standards and effective writing style. Finally, I cover processes of preparing, producing and managing documents.
My focus in this paper is on documentation that is intended to be printed and so is delivered on paper or in a format such as PDF which may be viewed on a screen or locally printed. Many systems now also have associated hypertext help systems. Producing these systems requires a different set of skills from producing paper documentation and I only discuss these briefly here.
[Show More]
