What makes a good manual?

Technical authors are often confronted with the spectre of the user’s manual when we mention what we do for a living. It is invariably the most universal example that we can give to shine a light on the largely hidden world of technical authoring, although it usually leads to someone recounting a story about instructions that completely failed to convey how to build or operate something, to which we can only shrug and mumble something about how companies should use professional technical authors to create such documents…

The fact is that it isn’t easy to write a good manual. One reason for this is that they are a regulatory requirement. The submission of a manual is a mandatory part of all the product compliance submissions with which we’ve ever been involved, and so it isn’t surprising that many clients request a manual as one of the first things that they need from a technical author. Products must be accompanied by some information which purports to help the end user to safely handle and operate the item. It must describe who produced it and what the potential hazards and risks are in using it. It must also attempt to anticipate the consequences of any misuse of the product and provide warnings and advice on how to avoid them. And therein lies part of the problem.

Manuals have often become repositories for every fragment of information needed to ensure compliance and limit a company’s liability, causing them to become bloated and difficult to navigate. If a company can say “it’s in the manual” then they at least feel that they are legally in the clear, even if this makes the manual so unwieldy and tedious to read that no-one bothers, thereby negating the benefits of all this valuable corporate wisdom. However, with the current popularity of seeking compensation, it seems unlikely that companies will strip out all this legalese from their manuals any time soon.

This trend certainly increases the need for manuals to be well-planned, carefully structured and clearly written to maximise their usefulness. Words should be used as economically as possible to convey the message clearly. Terminology must be unambiguous and consistent. Clear diagrams and photographs can be of great help although, flat-pack furniture assembly instructions notwithstanding, they are rarely sufficient on their own.

Careful consideration must be given as to what to include and, equally importantly, what to leave out. Where there are multiple ways of performing the same operation, something for which software is particularly notorious, there are often strong arguments against describing them all as it becomes too confusing, especially for a basic level new user. It can also be argued that most users do not need to understand exactly how a product works. While a superficial appreciation of what is happening can be helpful in using the product sensibly and diagnosing simple faults, an in-depth description, if needed at all, should be included as an appendix and not allowed to complicate or obscure the essential information.

Targeted manuals can offer a good solution against the tendency to include too much information. A quick start-up guide that covers the basics can be invaluable to getting a product up and running quickly. More advanced manuals for more adept users can follow later. Alternatively, looking from the manufacturer’s viewpoint, comprehensive service manuals can act as useful stores of product knowledge, containing valuable hints and tips gleaned as the product matures. These too need careful structuring and indexing if information is to be easily found, although the advent of electronic manuals now helps with this by providing a search facility. These documents can also act as valuable fault-finding guides for both users and technical support staff, and with email and the cloud allowing manuals to be rapidly sent around the world, the onus on the user not losing their one copy of the manual has reduced considerably.

Another important aspect of manuals which is easy to overlook is their role in supporting the company’s brand. The documentation that a user receives to help them understand and use a product says a lot about the company that supplied it. Not only should the manual adopt the same visual appearance as other marketing material, it should also feature the same style and ‘tone of voice’, so that it acts to support the rest of the company literature and reinforces the brand’s values.

The mandatory requirement for manuals, which can make them seem like a burden for companies to produce, can hide the great potential benefits that they can bring for both the manufacturer and the user – when they are well-written, of course!

© 2018 Tyndale Technical Authoring Ltd