Typical faults in poor documentation
In 1991, the Institute of Scientific and Technical Communicators published 'Quality and Professionalism in Documentation'. The article noted that technical documents often suffer from:
- Missing information
- Poor writing and ambiguity
- A failure to anticipate the readers' problems, questions, and environment
- Poor analysis of the readers—documents are written for the writers and their environment, not the readers and their environment
- The wrong technical level
- Poor formatting and design of structure
- Poor indexing—documents contain good information, but it is hard to find
- A professional appearance which belies the poor content
- A failure to match changes to a product
- Lack of planning
Next: Your solution to providing good software documentation.
