"Key Frustrations in
DOCUMENTATION MAINTENANCE
- and What to DO About Them!"

A product of:

DOCUMENTATION EXPRESS

DEFINITION OF DOCUMENTATION MAINTENANCE

The following definition is used throughout this report:

"Documentation maintenance" (frequently abbreviated to "maintenance") is the performance of those activities required to keep documentation operational and up to date after it is accepted and placed into production.

Documentation maintenance is the set of activities that result in changes to originally accepted documentation.

Generally, these changes are made to keep the documentation functioning in an evolving user and operational environment.

(Please note that there are many parallels between the maintenance of documentation and the maintenance of software.)

Functionally, documentation maintenance activities can be divided into three categories: perfective, adaptive, and corrective, as follows:

Perfective Maintenance

"Perfective maintenance" means changes, insertions, deletions, modifications, extensions, and enhancements made to improve understandability or maintainability.

Perfective maintenance is generally performed as a result of new or changing requirements, or to fine-tune the documentation.

Fine-tuning is an excellent way to introduce a new writer to the documentation, while reducing the probability of serious errors in the future.

Perfective maintenance is required as a result of both failures and successes of the original documentation. If the documentation works well, users want more features; if the documentation works poorly, it must be fixed.

Perfective maintenance can have dramatic effects on poorly written documentation by reducing resource requirements and by making the documentation more maintainable. Return to Table of Contents

Adaptive Maintenance

"Adaptive Maintenance" means adapting the documentation to changes in the environment in which it is used. Environmental changes are normally beyond control of the writer and consist mainly of changes to:

  • Rules, laws, and regulations that affect the documentation; these changes must often be completed quickly to meet dates established by the rules and regulations.
  • Equipment configurations, such as, new computers, new terminals, local printers, etc., usually to take advantage of improved features and/or pricing; normally performed on a scheduled basis.
  • Data formats, file structures, etc.; may require extensive maintenance if same were not properly designed and implemented. If changes are isolated to specific modules, they may have less impact, if not, the effort can be both lengthy and costly.
  • System software, operating systems, compilers, utilities, etc., usually performed on a scheduled basis. Return to Table of Contents

Corrective Maintenance

"Corrective Maintenance" means fixing errors - usually a reactive process where an error must be fixed immediately.

Not all corrective maintenance is performed in this immediate response mode, but all corrective maintenance is related to the documentation not functioning as originally intended.

There are three main causes requiring corrective maintenance:

  • Design errors. Incomplete or faulty design due to incorrect, incomplete, or unclear descriptions, or when the writer does not fully understand the user's needs.
  • Logic errors. Invalid tests, assumptions, instructions, and conclusions; faulty logic flow, incorrect implementation; usually attributable to the designer or previous maintainer. Often logic errors occur when user instructions and/or unusual combinations of data are not tested during development or maintenance.
  • Writing Errors. Incorrect implementation or design logic or incorrect use of special terms; caused by the writer. While they may be errors of negligence or carelessness, they are usually the easiest to fix.

NOTE: Many managers consider maintenance to include changing specifications or adding new capabilities. Return to Table of Contents

 

 

Return to Table of Contents