If your company manufactures a product that your customers or agents need to know how to install, operate or maintain, whether it’s a combine harvester or a software application, you need to provide them with the correct information, in the form of a manual or user guide. If you don’t do it well, you’ll get unnecessary enquiries to your helpline or customer support department and dissatisfied customers who might not come back. This article discusses some of the points to consider.
What is it for?
You need to have a clear idea of the purpose of the manual, in order to ensure that you include everything the reader needs to know but do not include superfluous and potentially confusing information.
What is it for?
It’s crucial to know the audience. What assumptions can you make about the reader’s existing knowledge of the subject and related technology; for example, if the manual is to describe the installation of a gas detector to an existing smoke detection system, will the reader be well-informed on smoke detection, but new to gas detection? Sometimes, the audience can be very well defined, such as military personnel. At the other end of the spectrum, the audience could be members of the general public and therefore vary considerably in their existing knowledge.
How will it be distributed?
Will you be producing small number of printed copies for internal or agent’s use, bulk printing for shipping with a product, or publishing on line? These decisions affect both the production tools you should use and the design of the document.
If you are going to laser print a small number of copies, a word processing application, with its many powerful text manipulation and automation tools, is probably best. If you intend to use a commercial printer, they are not keen on word processor output, so you will need to consider a page composition application.
Ideally, on-line documents should have a format compatible with a computer screen, so that scrolling is avoided, and should take advantage of the ability to link references within the document. If you intend to distribute in both printed and on-line form, you may have to compromise.
Will it be translated?
If you anticipate a need to translate from English into one or more foreign languages, be aware that they generally take up more space, as much as around 30%, in the case of German and most Scandinavian languages. Incidentally, perhaps surprisingly, simplified Chinese characters take up about the same space as English.
It is advisable to maintain a one-to-one relationship between pages in all languages used, to assist in responding to queries and making updates. You will therefore need to allow sufficient additional space on each page, or adjust font sizes, to accommodate other languages.
Who is going to create it?
What about knowledge of the subject matter – presumably the person who knows the subject matter best, such as the designer, is the obvious choice? In fact, this is probably not so, because they are likely to overlook what to them is obvious, but to the reader requires explanation. The author needs to be someone with an appropriate technical background but who will ask those questions that the reader might.
You may also need to make use of specialists, such as a technical illustrator.
The process
Having made all those decisions, it’s time to get started. You’ll need to design not only the format but also the content, in the form of a structure of headings. If you expect to use a lot of cross-referencing, it’s best to use numbered headings. It’s important to employ best practice by using the features of the application, such as styles and automatic numbering, cross-referencing and contents lists, to ensure accuracy, ease of updating and consistency. You need to be consistent in the writing too, so that the same item or function is always referred to by the same term. Consider the readership and purpose of the manual as you write and review what you have written. If at all possible, get somebody independent not only to proof read it, but also to validate it against the product – your customer should not be the guinea pig!
By Steve Morris