Introduction

Technical writing may not sound like the most exciting thing in the world, but (a) there’s a great need for it and (b) a huge degree of satisfaction is gained from writing user manuals that ordinary mortals can understand. A lot of user documentation appears to be written by technical staff for people who don’t need it — that is, other technical staff.

What’s the problem?

Once a somebody has purchased a product or service, what then? In my experience, a lot of great products are let down by terrible documentation. That doesn’t necessarily mean it’s been written badly. It may be good, but just not useful. It may be too detailed, lacking in detail, or it may fail to address one simple question: what does the user actually want to achieve?

Let’s take an example. Suppose a company sells a digital camera specifically designed for school use. It’s robust, brightly coloured, easy to see when it needs charging up, and so on. Although it has a few simple controls, teachers and pupils can do a lot more with it if they know where to look. Fine. The temptation is to write a manual that covers every single function, listed in alphabetical order. The manual, weighing in at 200 pages, is supplied in a pdf format, available online.

The box the camera comes in contains a “quick-start” guide which tells the user to start taking pictures straight away by pressing the big red shutter button.

What’s the solution?

Neither of these guides really address what the busy teacher, with a classful of kids probably wants to do, which would be:

• Take photos.

• Pass the camera around so that the kids can take photos.

• Get the photos out of the camera and upload them to somewhere central, where they can be viewed by the whole class and possibly others too, like parents.

• Charge the camera after use.

• Make room for more photos when the SD card becomes full.

None of that is rocket science, but each step could cause less confident teachers to worry: will the camera break if too many kids handle it? What if someone drops it or spills orange juice on it? What if I can’t get the SD card out? How do I put it back in? What if there are photos that we want to delete?

The differences between the all-encompassing pdf manual and the sort of manual that would address such points are:

• The user-centred guide is available: the information could go on a card, or an A5 sheet of paper. No hunting for, and then downloading and printing PDFs. No hunting through the index or table of contents trying to second guess what the writer may have called the thing you’re looking for.

• It’s pragmatic. It gets the teacher (and therefore her class) going right away. 

• It covers the subject from the point of view of the user, not the technical author who wrote that huge PDF. In this example, the section called “Taking pictures” comes near the beginning of the manual, perhaps followed by “Organising your photos”. In other words, the sections appear in the order that is most likely to be useful to a typical teacher rather than in alphabetical order. The starting point is the user, not the camera.

How To Write The Manual

Thinking of the user, consider these suggestions:

• Write different manuals for different people, or people at different levels of expertise. For example, an additional guide, to take the camera example, might be called “How to get more creative with your camera”. That would suit someone who has gone beyond “point and shoot”.

• Write in lists. You’re not trying to win the Costa short story prize. Use numbered lists where the order is essential; use bullet points where it isn’t. That’s a well-established rule.

• Include screenshots: a picture paints a thousand words and all that.

• If possible, get a teacher to write the manual (and pay them). As a general principle, it’s the target user of a product that is going to know how they will wish to use it — which may not be the way the product maker and technical team think it ought to be used.

• If possible, ask other teachers, and pupils, to test the manual or guide before you have thousands of them printed.

Concluding remarks

Don’t let your product be let down by poor documentation, or good documentation that has not been thought through. A printer I bought a few years ago had very precise instructions on how to open the packaging without damaging the contents. Great idea, marred only by the fact that you had to open the packaging to find it!

A well-written manual, perhaps with some humour, could even become a talking point in itself.