Documentation Utilities › Introduction

Introduction

The Toolkit documentation aids are based on simple fourth generation principles:

• Self-documenting systems:

  - Keep documentation on the computer as far as is possible.

  - Use the computer both to edit and to organize the documentation. Tools should be available to search and manipulate the documentation.

  - Make documentation available in the correct context: for example, help text for the displays of a program should be available when using the program; program descriptions should be available in the program source.

  - Make documentation complete and sufficient: it should be possible to re-create a system from source without the addition of further information.

• Structured documentation:

  - Keep only one version of the documentation.  The computer can be used to organize it into the various permutations that will be required.

  - Different users will have different needs: for example a system analyst needs to see a different level from a programmer. Ideally the different needs will be supplied by different routes through the same underlying data. Each level should contain information possessing a degree of detail appropriate to the level.

  - Keep documentation to a minimum: this requires the use of standard conventions for common types of documentation.

i OS provides you, in profusion, with the basic information needed to document a system. The Toolkit utilities help you to structure the information into a "documentation pyramid", that has different levels of access.

Note that as far as is possible, Toolkit documentation utilities enable you to generate documentation as a ‘by product’ of your normal activities.