Document Portability

• When a computing system is moved from one machine to another, the documentation associated with that system must be modified to reflect the new system. The work involved in this is comparable to the work involved in moving the programs themselves.
• If portability is a system design objective, the documentation must also be designed and written with the same aim.
• Self-containedness is the key to

1. program portability, and
2. documentation portability.

• Documentation portability means that the information provided in the documentation should be as complete as possible. Reference should not be made to any other documents, such as an operating system manual, which are not directly associated with the system being documented.
• Those parts of the system which generally cause portability problems are obviously the sections describing non-portable parts of the programming system. These include file organization, file naming conventions, job control, input/output, and so on. When the system is moved from one computer to another, those parts of the documentation must be rewritten.
• To make this rewriting easier, descriptions of system dependent functions should be confined to separate sections. These sections should be clearly headed with information about their system dependence and they are replaced when the system is moved to another installation. If possible, other references to system dependent features should be avoided. If this is impossible, an index of such references should be maintained so that they may be located and changed when the program is moved.
• As transporting a program and its documentation is really a specialized form of system maintenance, the availability of machine readable documentation and appropriate software tools reduces the work involved in producing documentation for a new system. System dependent parts of the document may be located, rewritten and a new version of the document produced automatically.