Software Documentation

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.