Document Maintenance

• As a software system is modified, the documentation associated with that system must also be modified to reflect the changes to the system.
• All associated documents should be modified when a change is made to a program. Assuming that the change is transparent to the user, only documents describing the system implementation need be changed. If the system change is more than the correction of coding errors, this will mean revision of design and test documents and, perhaps, the higher level documents describing the system specification and requirements.
• One of the major problems in maintaining documentation is keeping different representations of the system in step with each other. The natural tendency is to meet a deadline by modifying code with the intention of modifying other documents later. Often, pressure of work means that this modification is continually set aside until finding what is to be changed becomes very difficult indeed. The best solution to this problem is to support document maintenance with software tools which record document relationships; remind software engineers when changes to one document affect another, and record possible inconsistencies in the documentation.
• If the system modification affects the user interface directly either by adding new facilities or by extending existing facilities, this should be intimated to the user immediately. In an on-line system, this might be accomplished by providing a system notice board which each user may access. When a new item is added to the notice board, users can be informed of this when they log in to the system.
• System changes can also be indicated on a real notice board and in a regular newsletter distributed to all system users. At periodic intervals, user documentation should be updated by supplying new pages which describe the changes made to the user interface.
• Paragraphs which have been added or changed should be indicated to the reader.
• New versions of documents should be immediately identifiable. The fact that a document has been updated should not be concealed on an inner page. Rather, the version number and date should be clearly indicated on the cover of the document and, if possible, different versions of each document should be issued with a different colour or design of cover.