Ten considerations
How to write a technical manual? Technical writing always brings with it ten considerations that any technical writer should be aware of.
1. Know who you are talking to
Manual writing expertise is first and foremost: knowing who you are talking to. The tone of voice for elderly people using a tablet has to be quite different from a mechanic who knows his way around in a chemical plant.
2. Be aware of all directives
When a product is faulty in some way, the manufacturer or reseller can be held accountable for its consequences. ‘Faulty in some way’ is indeed the right expression, since European directives also include requirements for writing technical manuals (or any manual for that matter). This means that your technical manual is also subject to scrutiny. A manual is an integral part of the product and could lead to legal liability!
3. Follow the guidelines
Legal requirements or directives are all fine. But how do you know that you meet those requirements? Fortunately, there are guidelines. These guidelines may have a national origin. However, they do not differ much between, say, Germany and the Netherlands. Of course, one should be aware of these guidelines. They tell you what kind of chapters to include, what size the letters should be and so on.
4. Collect all the information that you can
It is better to choose from too much information than risking the chance that your technical manual (or not so technical manual) is incomplete. CAD illustrations? Marketing documentation? They all provide context and therefore should be an integral part of manual writing.
5. Write effectively
How to write a technical manual effectively? By using the manual writing expertise that you have at your disposal. There are at least three principles that lead to effective manual writing: Simplified Technical English (STE), minimalism and topic based authoring.
Simplified Technical English
Simplified Technical English is a specific standard, simplifying the use of the English language in technical documents by putting a limit on the number of words in a sentence. Also, the set of words is restricted (‘to do’ is easier to understand than ‘to carry out’).
Minimalism
Minimalism is a way of thinking. This way of thinking is: only provide information that is really useful. An example coming from the aviation industry springs to mind. When there was a loss of pressure in an airplane, the emergency manual – in effect a checklist – started with telling that something might be wrong with a valve. This certainly is a false start. The first sentence should have been: “Put on your oxygen mask.” Minimalism could have saved lives here, since the pilots did not feel inclined to put on their oxygen masks. And the checklist did not tell them to do so. Minimalism tells us we should concentrate on our tasks, not on information that can be provided later on (or is not necessary at all).
Topic based authoring
Topic based authoring means that writing (technical) manuals comes down to writing building blocks that can be reused in other or newer technical manuals. For example, the chapters or sections ‘Safety measures’ and/or ‘Maintenance’ could be identical in different manuals. By writing topic based, instead of writing in a linear fashion, information blocks become readily available all of the time.
Using these three principles will shorten training times for mechanics with as much as 30%. Users can absorb 25% more information as a consequence of bringing the three writing principles into practice.
6. Use pictures
Writing techical manuals should not only include… manual writing. Even better still: writing technical manuals should preferably not entail writing manuals. If a picture tells you more than a 1,000 words, the illustration should take preference. An illustration can be far more effective if you want to get your message across. Illustrations may also be more cost effective to produce. At any rate, translation of a picture will not be necessary.
7. Use animations
When a user has to carry out a lot of similar actions (holding the top of a bottle while moving the rest of the bottle to the left, then putting the bottle upside down and so on), a series of illustrations might be effective. But an animation might be the extra option you are looking for.
8. Translate and… localise
It could be that your manual needs translation, if only because of European directives. It goes without saying that texts in a local language are also very user friendly: almost everyone likes to be addressed in his or her own mother tongue.
Translation should be more than replacing words. It should also entail ‘localisation’. What does ‘localisation’ in a manual mean? It means that for users on the European continent the steering wheel of a car should be drawn on the lefthand side, whereas for UK users it should be on the righthand side. To you give just one example.
9. Build your archive
It is important to use content management software with which you can build your own archive. This way, you can easily use and reuse existing information blocks.
10. Publish in any (additional) shape or form
Why is a content management system so enormously important? Because you can reuse existing information blocks in every output channel imaginable: print, online or offline on a device (by means of a PDF file, for example). Online or offline presence also makes it possible to use 3D animations.