How to make a manual

Making a manual: some considerations

Making a manual doesn’t seem to be that difficult. This may be true, but experience shows it is quite a challenge to write a manual that serves its purpose as a set of effective instructions for the user. Why is this so? Writing down working instructions is quite simple: one uses simple, imperative sentences (“Press the Start button”). If the list of instructions becomes too long, one subdivides a task into separate tasks. Why then, are so many manuals suboptimal at best?

It is best to start on time

Probably, writing a manual does not get immediate attention. The product itself takes priority. Manual user design becomes something “to do in the future”.

The problem is: the future can suddenly be here. That is why making a manual should be an integral part of any product develoment right from the start.

The question how to write a manual should always include the question: what should be the planning for writing a manual?

What to plan for? Well, there are eight points to take into account. They all take a certain amount of time. These points do not imply that each and every one of them is a separate task that requires your attention. Situations differ per company. However, the eight points give an overview to get any user manual design started on time. Also, these points reduce the chance of producing a owner’s manual too late.

Here are the eight considerations that each could take their time. It is, in effect, a checklist to make sure your planning includes everything you need. Make sure that there is a project leader to keep track of everything .

Eight considerations

1. The tone of voice for your customers

Should one write in a formal way (say for software engineers) or an informal way (say for first time users of consumer products)? This decision need not take much time. You already know a thing or two about your customer base.

2. National and international regulations

Here some research is needed, or maybe already done. Specialists, like Manualise, probably know best how to comply with regulations when making a manual.

3. Collecting all available information from colleagues

It is always a good idea to start this task immediately. This will save a lot of time later on. One could combine this task with the previous tasks, in order to speed up the process.

4. Writing the manual itself

Here some simple rules come in, like: use imperative sentences and subdivide tasks if a task involves more than – say – eight instructions. How much work is involved? The project leader knows best.

5. Inclusion of pictures

A technical writer and a technical illustrator could be one and the same person. But if they are not, one should ensure that both work together as soon as possible.

6. Translation and localization

Freelance translators or translation agencies can give an indication how much time translating and localizing will take.

7. Publication by using the different output channels

After making a manual, it needs to be published. Generally speaking, a publication on the basis of different output channels (such as print, laptop or tablet/smartphone) does not take extra time. When using a content management system like MadCap, content is stored centrally. One can use this content over and over again.

8. Updating content

This task only becomes relevant after finishing a manual. When using a content management system specifically geared to technical documentation, updated information immediately can find its way to all online outlets. These outlets could be a laptop, a desktop, a smartphone or a tablet. Printed versions of your manual take printing time of course.

Each situation and each project is different, making it difficult to give general indications of the time needed. A single manual takes less time than a project with multiple manuals in multiple languages. When a project tends to become rather complex, outsourcing may be a solution. Experts can give a reliable indication of the time needed, based of course on the wishes of their client.

Costs and benefits

Sofar, costs – if only in time – have played their part in this article. Which are the benefits of a good planning? When publishing an optimal instead of suboptimal manual, there almost certainly will be less helpdesk costs. This could save quite some money, in some cases up to 40%.

Also, well planned and well thought out manuals are easier to ‘assemble’ if a new or similar version is needed. That is why topic based authoring is so important. This is a method to write separate information blocks instead of writing in a linear fashion. Linear writing does not lend itself for reuse, topic based authoring does. Reuse could save you at least 50% of your time time when starting your next manual project.