Choosing writers for equipment manuals
In order to choose a writer to work on equipment manuals, you first have to work out what type of information is to be included in the manuals. The content and structure of equipment manuals is not fixed but depends heavily on:
- The type of equipment.
- The complexity of the equipment.
- The environment of use. The conditions under which it is used.
- The maintenance philosophy. Who is going to maintain the equipment, where is it going to be done and with what resources.
Classes of information included in equipment manuals
The range of information which might appear in an equipment manual is diverse and is best considered under five classifications:
- System information.
- Installation information.
- User (operating) information.
- Maintenance (service) information.
- Technical information.
These classes of information are discussed below.
Some equipment items form part of a system and the first element of information describes the system at a high level using diagrams and describing:
- What the system does.
- How the equipment fits into the system and what part it plays.
- How to test the system.
- How to verify the interoperability of the equipment item within the system (Systems Interoperability Testing).
Note: Depending on the complexity of the system, there may be significant amounts of information covering user, installation, maintenance, and technical information at the system level as well as at the equipment level.
This involves all the procedures required for securing the equipment into place and preparing it for use (interconnections, etc). This should lead directly into the user set-up and placing into service procedures without gaps or overlaps.
If the installation of the equipment is beyond the capability of the target user (i.e. If it is a complex procedure and/or if it involves a trades skill) this class of information may warrant a separate technical manual or bulletin, or inclusion in a Technical Manual.
This may include such information as:
- Suitable OHS & R information in the form of warnings and cautions, recommendations, etc.
- Relevant standards (electrical, mechanical or plumbing).
- Dimensions in the form of diagrams or templates.
- Procedures for installation and any preliminary testing or verification required.
User or operating information is by far the most common type of information included in equipment manuals. This information describes for a (usually) non-technical user how to set up and use the equipment.
User information will cover the following areas:
- Suitable OHS & R information in the form of warnings and cautions, recommendations, etc.
- The purpose of the equipment. What the equipment does and what the user can expect to get out of using it.
- Brief specifications. Simple stuff such as types of interface connectors, etc.
- Description of controls (what they do), indicators (what they show) and connectors (where they go). This usually takes the form of diagrams and tables showing and describing each item and its intended use.
- Installation procedure. This would be included as user information if it is simple (such as plug it in and switch it on). More complex installation procedures should be included in the installation class.
- Set-up procedure. How to get the equipment going, place it into service and verify its correct operation.
- Operating procedures. How to perform the operations intended for the equipment.
- Simple faultfinding and rectification of minor faults. This could include such things as power on, plugs disconnected, correct operating selections, etc. May include escalation to higher levels of maintenance for more serious faults.
The language for user information is chosen to suit the level of understanding of the intended user and would normally be aimed at a fairly low level.
Note: There are obviously some common areas here with software user manuals since the operation of many equipment items involves software-like functions with the use of menus and displays. Operating instructions may include screen shots, etc.
Some equipment items are designed to operate in conjunction with controlling software intended for loading onto a PC. Operation of this software would take the general form of a software user manual.
There are two categories of maintenance or servicing information:
- Preventive.
- Reactive.
This covers maintenance undertaken on a planned basis to prevent failure due to foreseeable or preventable causes, and to detect incipient failure before it becomes critical. Also called planned, periodic or scheduled maintenance.
This is usually based on a periodic schedule or checklist of maintenance tasks giving the following information about each task:
- Priority. How important the task is and what impact it will have if not performed.
- Frequency. How often the task is to be performed (daily, weekly, monthly, etc).
- OHS & R. Hazard information in the form of warnings and cautions, recommendations, etc. This can include electrical shock hazards, risks of asphyxiation from fumes, flammability risks and avoidance of skin and eye damage.
- Maintenance procedures. How to perform the various maintenance various maintenance tasks, step by step.
- Verification. How to check that the task has been done properly.
The tasks involved could include:
- Cleaning.
- Inspection for damage or signs of deterioration.
- Simple procedures for replacement of easily accessible piece-parts such as knobs, indicator lamps, etc.
- Changing and/or charging of batteries.
- Testing to verify performance criteria, and a procedure to follow if the test fails.
This covers maintenance aimed at restoring failed equipment to service, usually called Repair or Service Manual.
- Diagnostic procedures. These could be based on flowcharts or tables which lead to diagnoses, or could involve testing procedures, the result of which guide diagnostic decisions.
- OHS & R. Hazard information in the form of warnings and cautions, recommendations, etc. This can include electrical shock hazards, risks of asphyxiation from fumes, flammability risks and avoidance of skin and eye damage.
- Removal and replacement procedures. Detailed procedures for removing and replacing faulty items.
- Testing procedures to verify that the repair has been successful.
- Repair parts identification listing. Information to aid in the correction selection of replacement parts.
The language for maintenance documentation should be aimed at the skilled tradesman using nomenclature appropriate to the discipline involved.
Note: In some cases, the maintenance may be broken down to discrete procedures at different levels of skill. For example, where there is a differentiation between maintenance to be carried out at the point of use, and that to be carried out in a factory or similar facility (where more equipment and/or skills are available).
This is in-depth information for the technical (engineering) people:
- To provide understanding of the underlying principles of the technology and its application to the design.
- To provide background for the investigation of the feasibility of enhancements or modifications which may be required to improve reliability or performance.
- To enable senior maintenance personnel to diagnose faults when normal servicing procedures have failed to do so. Enables a technician to "knife-and-fork" a repair if required.
The language for technical documentation should be aimed at the design engineer using nomenclature appropriate to the discipline involved.
Note: Most manufacturers will elect not to publish this level of information because of its commercial sensitivity. They may choose to rely on their internal engineering documentation for this. To do so is fraught with difficulty since engineers are traditionally not good documenters and tend to write to their own level of understanding. This leaves most others with a gap when trying to link first principles to the application of them.
Very few manufacturers will undertake to produce a separate manual for each class of information. They will attempt to combine the information in a more practical suite of manuals to best suit and support the equipment
- At one extreme is the Army model (according to Defence standard DEF AUST 5629A), where the documentation of an item of equipment is produced as a suite of 10 or more discrete documents covering all aspects of the equipment:
- At the other extreme is a small item of equipment for which a single manual is produced covering all relevant aspects of its operation including all maintenance and repair information, and a parts list.
As usual, the best and most practical compromise is a simple split between user information and technical information. The most usual combination is:
- A User Handbook incorporating installation procedures, operating instructions, simple preventive maintenance procedures (such as cleaning, etc) and simple faultfinding instructions. There is a difficulty here since we have a single manual addressing two or perhaps three different audiences. If installation is complex, a separate manual or technical bulletin may be required.
- A Technical or Service Manual, incorporating a brief technical description, full preventive and reactive maintenance information, a parts lists and a selection of the detailed drawings sufficient to allow the maintenance procedures to be carried out.
User information: The writing of equipment user documentation is not a particularly specialised area and most competent writers who have produced software user manuals could handle it, although a background in producing hardware documentation and/or in the discipline involved would be an advantage.
Maintenance Information: This is a specialised area for technical writing and, when choosing a writer, look for someone who has a technical background in a related discipline (preferably in the maintenance area) and/or some experience in this type of documentation.
Technical Information: This type of documentation is extensive and complex and requires a specialist technical writer preferably with a solid background (preferably engineering) in the relevant discipline, some practical knowledge of the application, and some experience in this type of documentation.
At one end of the scale this could be simply a brain dump from the designer, or at the other end an exercise in hardware reverse engineering.
Illustrating: Equipment manuals will almost certainly involve an illustrative component, ranging from simple block diagrams to 3D CAD and perspective rendering of equipment views. This is a specialised area and beyond the capabilities of most writers. This applies particularly to the illustrated (exploded) parts list category of information.
Never assume that the an engineer will produce or be able to produce the required illustrative material.
- At best, expect that an amount of graphic file manipulation will be needed to adapt the existing drawings; make sure the writer is up to this.
- At worst, you may need a specialised technical illustrator or draftsperson to produce or adapt suitable material.
The recent advances in digital photography technology make this a bit easier since, in most instances, a good photograph will do the job.
This article may be reproduced only with the permission of HCi (email HCi ). Copyright HCi, 2001-2.
