Practical Software Engineering

Documentation and Manuals


Poor quality documentation is the second most common problem reported in software maintenance (the first is user demands for enhancements and extensions)

A typical list of documentation for a programming project

  1. Request for proposal *
  2. Proposal document *
  3. Any studies, papers, reports which support items 1 and 2 **
  4. Preliminary specifications
  5. Preliminary design document (memo plus flowchart, pseudo-code, etc.)
  6. Detailed specifications
  7. Detailed design document (formal report plus flowcharts, pseudo-code, etc.)
  8. Documents supporting unit testing (test plans, lists of test cases and expected results, lists of errors, programmers' notebooks)
  9. Documents specifying how configuration control is to be performed.
  10. Documents supporting integration test (test plans, list of test cases and expected results, lists of errors, programmers' notebooks, computer records)
  11. Forms describing each error by number and how it was discovered, the diagnosed cause of the error, and how it was corrected
  12. Acceptance test plans and results
  13. Field test plans, operational notebooks, and results
  14. Documents resulting from design reviews or management decisions
  15. Any related specifications and design guides.
* In the case of an in-house project, memos of direction and intent may serve the same role as these documents.

** Copies of the contract; any quality assurance plans and documents; engineering studies of reliability, memory requirements, processing time, or prior engineering or feasibility studies, etc.

Nobody reads documentation

M. Rettig, Communications of the ACM, 34(7), 1991 pp.19-24.

Most documentation is written by technicians, yet technicians frequently complain about it.

Forms of documentation

Why do users not read documentation?

Minimalist manual

Software designers and technical writers should interact throughout the design lifecycle.

Documentation should be viewed as a creative challenge to provide information for end users.

Manuals -- Mayrhauser section 11.3

Manuals should:

Contents of a Training Manual

1. Introduction 2.-k. Successive learning steps Appendices.

A.1. glossary of terms

A.2. index

A.3. short alphabetical reference section of commands (maybe as a card)

A.4. collected error messages

Contents of a Reference Manual

1. Introduction 2.-k. Components and features Appendices

A.1. error messages, explanations, effects, system status, possible actions. Cross-reference to section that explains system component or feature.

A.2. index

A.3. short, alphabetically ordered reference card for commands.

The Mac is Not a Typewriter

R. Williams, Peachpit Press 1990.

Checklist for Documentation and Manuals

Practical Software Engineering, Department of Computer Science 10-Jan-96