Table of contents
Definition of a good manual
The definition of a good manual focuses on just one word: action-oriented. A manual contains instructions to get something working or keep it working. That sounds very obvious.
Yet there are many manuals in circulation that are not actually action-oriented at all. It is quite conceivable that a manual first describes what a valve is for. Or what advantages this valve has compared to other valves. Or which color combinations of the valve are available. Someone who wants to operate, repair, maintain or replace the valve is not interested in this information. He or she wants to get started.
Types of manuals
What types of manuals are there? The answer is: there are as many manuals as the different purposes the manuals must meet.
The best known are the user manuals: manuals that explain the use of a product or software. If a separately assigned operator is required for the product, such as a machinist, a user manual is often called an operating manual. But the term “user manual” is the most common.
Anyone who needs to install a machine needs an installation manual. These manuals are common. A production machine requires a fairly extensive installation: from anchoring to the floor to a specific connection to the mains to the installation of safety features (such as transparent screens). The installation procedure for a printer fits into the first chapter of a user manual. But commissioning a welding robot or traffic light almost certainly requires a separate manual.
Sometimes the products are so complex that special maintenance manuals are also required. Think of a commercial aircraft that needs to be examined or refurbished every so often. When an inspection is required and when a complete overhaul is required, it is stated in the maintenance manual. These manuals are indispensable for complex products such as aircraft, ships and trains. They are also indispensable for passenger cars and trucks. There are many maintenance manuals on the shelf in garages.
A user manual often has a concluding chapter called ‘Troubleshooting’. Complex products in particular often require special manuals that actually list a complete collection of error messages. Such an error message often has a code, for example EK76-AA: “Green lamp triangle signals no locking of the landing gear”. In this specific case, a troubleshooting manual indicates what the crew of an aircraft must do. Perhaps the landing gear is functioning, but the problem is with the lamp signaling. A troubleshooting manual contains instructions to identify the exact problem and to resolve it as much as possible.
Criteria for a good manual
A number of writing rules determine whether a manual has a high, medium or low quality. An obvious writing rule actually came up earlier in this article: a manual should contain instructions. Background information about the availability of valves in different colors does not belong in a manual, but in a brochure. So: do not write in a manual why the carrying capacity of an aircraft is optimal. Write how to safely tension the control cables so that the ailerons on the wings operate safely.
Shouldn’t there be any background information in a manual at all? To be honest, some background information is useful. However, there is a condition: that background information must be minimal. Moreover, the background information must serve the purpose of the action orientation. An example makes this concrete.
Suppose that the system for breaking off ice from an aircraft wing has a completely new variant (ice on the wings can seriously affect the carrying capacity of the wings). Then it is a good idea to mention this in the manual. After all, such a new system can mean that the operation is different. To prevent anyone from clinging to the old way of operating, it is good to note that the ‘de-icing’ system now works with different technical gadgets. Suppose the new system works much faster with even the smallest amounts of ice. Then the user – here the pilot – knows that much faster activation is possible. A faster activation can only work better to remove all the ice from a wing right from the start. The pilot is, as it were, given a new mental model that makes him think differently about the necessary actions.
Such background information serves the purpose of action. But this information should also be minimalist, that is, there should not be too much background information in a manual. Then the focus on action disappears. This action-oriented nature means that the manual clearly states: such-and-such buttons are needed to switch on the ‘de-ice’ system.
In summary: as a technical writer, provide a mental model of the background of actions, insofar as the reader is not already familiar with that mental model. But be minimalistic with the information provided.
Anyone who follows this middle path and emphasises action-oriented instructions (“Click the white toggle switches up at the same time to activate de-icing on both wings”) will write a good manual.
Tips for the layout and design of manuals
So far this article is about the contents of manuals. But an attractive presentation is just as important.
‘Presentation’ in a manual is divided into two parts.
First of all, the design must be attractive. This means, for example, that a manual has a modern, sleek appearance that matches the manufacturer’s corporate identity. Such agreements are recorded in a so-called ‘template‘: a template with an overview of the formatting rules created.
These formatting rules not only provide an attractive appearance, but contribute to readability. An example: if the manual is about a mobile phone specifically intended for people over 50, then it is certainly worth considering increasing the font size slightly, for example from 11 points to 12 points.
In addition to an attractive design that enforces readability, ‘presentation’ also includes the use of images. People are visual, they have traditionally been used to thinking in images. The well-known saying “A picture says more than 1,000 words” stems from this. Writing is only thousands of years old. The visual experience of our ancestors may be 100 times older. In short: a good manual uses pictures whenever possible. Pictures say a lot, all at once.
Examples of good and bad manuals
There are plenty of examples of good and bad manuals. To start with, an example of a bad manual.
A manual for an unnamed washer dryer combination looks good. However, closer examination reveals a number of classic errors:
- If the combination makes too much noise, it is advisable to level the device properly. However, the mentioned reference to the ‘Assembly’ chapter is inappropriate, because it is not in the manual. Is there perhaps a separate (not included) installation manual? This is not clear.
- Sometimes the manual talks about ‘water softener’ and other times about ‘water softener’. Does the manufacturer mean the same thing here or are these two different pieces of advice for keeping the machine in good condition?
- The chapters do not always have a clear title. This is how the three most important chapters read in succession:
- Daily use
- Daily use: dry only
- Daily use: wash & dry.
The difference between these three is not immediately clear. It would have been clearer if it had stated under a.: ‘Daily use: wash only’. Now the reader must puzzle over what is meant by daily use.
- The texts continue continuously, not only after a paragraph but also after a chapter. So a new chapter does not start on a new page. This creates pages full of text without giving the reader a clear sense of the layout of the manual.
There are of course also examples of good manuals. These are manuals where references to other pages and manuals are always correct. This is also a manual where the terminology is clear: so do not mention the word ‘lid’ one time and the word ‘cover’ at another.
Take a multifunctional internet box supplied by an internet provider. Fortunately, the following chapters appear to emerge clearly: Watching TV, Surfing the Internet and Calling. It sounds simple and it is. But keeping something simple is sometimes not easy, see the example of the washer dryer combination.
Have manual written by Manualise
A manual that meets all professional and legal requirements, but above all the wishes of the customer: that is the minimum aim of Manualise. Based in the TU city of Delft, all technical writers have a background in technology. They all have training that brings together technology and language. That language certainly does not have to be a language consisting solely of words. On the contrary: Manualise relies on its visual attitude. Where a picture can do the job, the company uses an image. The ultimate goal of this young company is therefore: the best of all worlds.
