Readability/Usability/Quality 1-01 (March 2001) by Åke Rullgård

Documentation, operators’ manuals, maintenance instructions, etc, can never be perfect and satisfy all users. The organization of the documentation, particularly for large systems, will never suit all users and there will always be some errors present. This means the supplier and the user need to cooperate in various ways to avoid the fatal consequences of errors and misinterpretations, and for the improvement of documentation over time.

This article proposes some procedures and methods for such cooperation. The ideas suggested below apply, with obvious adjustments, to documentation on paper as well as documentation stored electronically. The proposed procedures should be applied at each level of the production process of documentation, i.e. also between the main supplier and possible sub-suppliers of, for instance, measuring equipment and other sub-systems. This article also aims at opening a discussion in TC- Forum on methods for improving documentation. Readers, suppliers and user are therefore welcome to submit comments on the ideas presented below.

1. The supplier shall always, as an integral part of the documentation, submit a list of all papers, i.e. drawings, manuals etc, forming the complete documentation for the product or system. The list shall specify each paper in complete detail, such as full bibliographical data, document id-number, issue, origin etc. This will facilitate establishing safe and efficient specifications for each paper.
    
   The list shall further clearly state the product or system for which the documentation is valid. Prior to delivery, the supplier shall inspect the documentation regarding readability to ensure the information has not been mutilated in some way. For documentation on CD, the document shall be checked carefully so that the corresponding digitized version can be unambiguously read on the screen. For full clarity, the responsibility for correctness of facts always remains with the manufacturer of the documented product.
    
   
2. If the complete documentation is contained in a single, bound manual it is practical to include a remark such as: "This manual contains the complete documentation for product X". In such cases the list described as item 1 is not needed.
    
   
3. Upon receiving the documentation, the user shall immediately check that all papers listed according to item 1 have been received and that the bibliographical data found on the papers agrees with the data in the list. Any discrepancy between the list and the papers shall be reported immediately to the supplier, who shall return corrections to the user.
    
   
4. It is also important that unlisted papers are reported. Consequently, the formal check constitutes a good base for determining the coming use of the documentation. It also forces the user to become thoroughly acquainted with the documentation. (This effort is comparable to a procedure applied in delivery control, in wich the received goods are checked against a packing list, a procedure applied in all delivery control systems.)
    
   
5. After completion of item 3, with possible corrections from the supplier, the user shall inspect the documentation to determine its readability and, where readability is weak, report possible difficulties to the supplier for corrective actions.
    
   
6. The user shall identify any errors and ambiguities found when applying the documentation, and shall report them to the supplier. The supplier shall respond immediately with corrections and/or clarifications.
    
   
7. Documentation for large systems, e.g. documentation for a plant, should contain the supplier’s description of the principles behind the organization of the documentation, plus advice on how to use the documentation to find special items such as components and maintenance procedures. For documentation on CD, this section corresponds to software for navigation among the various papers, which can of course be highly automated.
    
   
8. It is essential that the supplier establishes an efficient and reliable system for communicating corrections and updates to the documentation. This system shall be designed so that it facilitates user implementation. Similarly, it is also essential that the user immediately inserts the corrections and cancels obsolete documents.
    
   
9. Users are urged to report experiences, positive as well as negative, from use of documentation in magazines such as TC-FORUM, preferably in a neutral way, i.e. without mentioning the supplier’s name.

"transline Deutschland - Übersetzungsdienst für technische Übersetzung"