Uncategorized

How to write a ‘how to’ document

So, your organisation has to produce a document. Maybe it’s an instruction manual, a code of practice, a policy document… anything that tells people how to do things or what the rules are. Where do you start?

As always, start with what you want to achieve. Who has to get the information, how will they access it and what do you want them to do?

For instance, if you’re selling a product that needs some assembly, then a small sheet of paper with a few numbered, illustrated steps may be enough. If the topic is complex and people need to be able to refer to a manual, then a well-indexed online on printed volume might be needed. If it is a form than needs to be filled in on your website, an interactive program with prompts is probably best. And some things are best explained through a video or animation.

Knowing the audience is also important. What do they know already? How much needs to be explained to them?

One of the hardest things when writing a ‘how to’ document, is gauging how much the audience knows. You don’t want to treat them like they’re stupid, but you don’t want to assume they know something they might not. (It is always a danger that experts cannot imagine the things that non-specialists don’t know.) A good way around this is to slip in the required information in a way that doesn’t come across as didactic.

For example: The instruction boil an egg for eight minutes when you want it hard might be an insult to an experienced cook. On the other hand, other readers may not know this. So, what you do is present the information while making another point: After you’ve waited eight minutes for the egg to boil hard, consider the dilemma of Schrödinger’s cat.

The structure of ‘how to’ documents is vital. Work logically, building up from the basic to the specialised. Explain how to switch on the machine before you explain how to switch it off. Go from the general to the specific.

There is no one-size-fits-all recipe, it all depends on the amount and complexity of the information to be conveyed. To structure the document properly, the writer has to have a solid grasp of the information and how it will be used.

Then, of course, the information has to be presented clearly – both in how it is designed and how it is written. Keep the language simple, avoid jargon and explain acronyms. Use illustrations or animations where it makes sense to do so. Then read it as if you’re a wilful dimwit, to weed out any ambiguity.

When the whole document is drafted, test it by giving it to others to read, experts as well as others.

Making things simple is a complex process.

Writing instructions, manuals, etc., happens to be something I love and I’d like to think I’m quite good at it. Give me a call on 021 798 645 or email zirk@saycommunications.co.nz about your project. It will cost you nothing to have a chat and, at the very least, you might get some helpful suggestions.

Leave a Reply

Your email address will not be published. Required fields are marked *