5. Manuals and Handbooks
Maintenance manuals and user guides, parts catalog(ue)s and operating handbooks are classified under the umbrella heading of Customer Support Documentation. Whatever the length and cost may be, they are written with a common aim, that of providing the user with accurate and relevant data about a particular product.
The preparation of a technical manual involves a number of distinct steps but can be broken down into three phases: outline and design, development, and production. For the present we shall concern ourselves with the general format of a technical manual — what it looks like, and the specification (house-style) governing it.
A specification is a document prepared by an authority (Standards Institution, for example) setting out in some depth, the format, presentation, heading-weights scheme, style and shape of a technical handbook. Nothing, in theory, is left to discretion, and the object is total standardization between documents. The standard British handbook specification is BS4884, produced by the British Standards Institution. Specifications are dealt with more fully later.
In general, the terms of reference of any writing contract, including the specification, are laid down at the outset by the commissioning authority. If this organization is a commercial company, it may have its own in-house specs, at the least a house-style.
The British Standards Institution defines the scope of BS4884 as specifying “information to be given in technical manuals and other documents designed to facilitate the use, maintenance and repair (where appropriate) of any material or product.” The Institution suggests a nine category division of the book, or books:
1. Purpose and planning information (What it’s for)
2. Operating information (How to use it)
3. Technical description (How it works)
4. Handling, installation, storage, transit (How to prepare it for use)
5. Maintenance instructions (How to keep it working)
6. Maintenance schedules (What is done when)
7. Parts list (What it consists of)
8. Modification instructions (How to change it)
9. Disposal instructions (How to get rid of it)
The nine categories have been designed to cover all the information that a product’s user is likely to need. The order of listing is to some extent arbitrary (though particular to some applications), and may be altered as necessary. The standard also explains that “the extent of the information provided will depend on the nature of the product, the user’s needs and the maintenance policy; some products will not require any supporting information and others will require only some of the categories.”
Manuals supporting highly complex equipment may consist of a single volume for each category. A simple appliance might use only one or two categories in a single folded sheet of paper.
As a structure for the organization of a technical manual, BS4884 is a useful arrow in your quiver, whichever country you’re writing in. If a client has no particular specification in mind when approaching a writer, this system may be suggested. Both client and writer will then have a basis for further discussion, and the expectations will be broadly in line with the material produced.
Further division of the nine categories into subdivisions turns BS4884 into an extremely helpful pigeon-hole system in which to allocate the mass of technical data generated by modern industrial and military equipment:
1. Purpose and planning information
Provides the user with information relating to suitability of the product for particular applications.
Performance: Limits of performance. Handling requirements, physical dimensions and weights. Limitations on environment and reliability.
Sources of information: References to documents, specifications, patents, and so on.
Hazards: All known hazards.
2. Operating information
Contains lucid instructions for operating the equipment under all conditions.
General: Reasons for particular points in operating procedure. Details of each user control. Manual/automatic/remote control. Safety precautions.
Operating instructions: Step by step instructions for preparing, starting, operating and shutting-down the product in all modes under normal and emergency conditions.
Hazards: Safety monitoring devices. Warnings of hazards arising from misuse.
Malfunction: Procedures to be used during malfunctions, or when affected by external hazards.
Disposal: Safe methods of disposal of part, or all, of the equipment, and the dangers involved.
Correcting malfunction: Detecting malfunctions. Operator correction procedures.
Planned sequential procedures (drills): Critical procedures. Strict drills for operation. Consequences of not following exact sequence.
Presentation: Procedures (drills) for a team of users — each member clearly delineated.
Practice drills: Exposition. Distinction between practice and operation.
3. Technical description
Provides descriptions on the functioning of “state of the art” equipment.
Purpose: General background and purpose of equipment.
Systems: Interface data for complex systems.
New techniques: Specific to unfamiliar designs. May be covered in an annex.
4. Handling, installation, storage, transit
Contains the technical information required for storing or relocating the equipment.
Reception: Unpacking instructions. Special points.
Installation: Installing and setting up the equipment. Test schedules and performance parameters. Connection of services (electricity &c). Precautions.
Setting to work: Preparation for use. Special tools. Test equipment.
Storage: Requirements for storage. Storage life. Tests and inspections. Use after transit.
Environment: Environment required for all uses.
Hazards: As considered necessary.
5. Maintenance instructions
Information based on likely resources available to the user. Special tools or materials. Maintenance procedures.
Tasks: Routine maintenance. Checks and inspections. Fault diagnosis and corrections. Overhaul.
Details: Instructions for each task. Warnings.
6. Maintenance schedules
Cycle of maintenance routines, and lists of tasks, time intervals or run-time of equipment.
Tasks: Schedules for each trade in order of frequency.
Complex products: Schedules for a team of maintainers.
7. Parts lists
Contains information for location and identification of all replaceable items.
Content: Assemblies, subassemblies, replaceable parts. Illustrations of parts.
Identification: All relevant information allowing identification of part and/or re-ordering.
Other information: Availability of spares, maintenance levels of replacement.
Short lists: Lists of consumable, disposable or short-life items, and kits for options or typical maintenance procedures.
8. Maintenance instructions
Modifications: Authorised changes and improvements. Separate publications may be necessary to inform users of modification to the equipment.
Instructions: Detailed instructions for modification. Additional items required. Identification of products requiring modification.
9. Disposal instructions
Disposal, demolition &c and hazards.
Part 2 of BS4884 “specifies requirements for the layout and preparation of technical manuals…” The standard recommends precise information for the layout of the front cover of the book, its spine, title page, and preliminary pages (prelims).
Other topics covered include types and weight of heading, illustrations, references, production of camera-ready copy, and indexes.
Handbooks written for the consumer market usually fall into two categories: User Guides and Maintenance Manuals. They are often formatted for visual impact and present different problems to that of the industrial document.
User maintenance is not encouraged by some manufacturers, even to the extent of voiding the warranty if certain screws are tampered with. It must be admitted that there is often some point to this restriction, especially for solid-state electronic equipment, though it must be said that the withholding of information is mostly done for other reasons.
However, in writing any maintenance manual three distinct levels of maintenance and repair can be identified:
1. Simple maintenance: This may include cleaning, replacement of discrete parts, oiling, simple test procedures, correction of minor faults.
2. Technical maintenance on location with limited resources: Of the type that a visiting television repair person might perform.
3. Workshop technical maintenance: Carried out by trained technicians with all necessary resources.
This threefold division illustrates a prime concept in all fields of technical authorship: level of readership. All books must be written with the prospective users in mind. Their level of skill and technical knowledge dictates the depth of treatment, and even style, of a technical handbook. In writing a maintenance manual, this three-point division of skill and resources should be considered of prime importance.
The user manual or guide is normally a straightforward operating instruction book containing some guidance on troubleshooting and a prominent referral to the repair network of the manufacturer or importing agent. It can range from a Hong Kong interpretation of a Japanese original printed on rice paper, to a sturdy paperback book written in a user-friendly style. Perhaps we should not judge a product by the quality of its supporting documentation, but the suspicion is always there.
Next: 6. Technical Reports.
