Guidelines and manuals

Guidelines and manuals usually contain operations or steps that must be explained clearly. This kind of writing will be most clear and accessible if it is written with the experience of the target user firmly in mind. Guidelines and manuals include:

• operating instructions and technical manuals (e.g. how to use a blender)
• troubleshooting guides (e.g. how to fix problems with a DVD player)
• guidebooks (e.g. how to spend 2 weeks in Provence)
• cookbooks (e.g. how to cook specific recipes).

Consider the end user

Understanding your audience is key for all types of publications, but particularly for technical writing. Very different texts may be required, depending on the end user. For example, a computer manual may be written for any or all of the following:

• a tentative beginner who has never owned a computer and is unsure how to start
• a confident subject-matter expert who wants every detail of how the computer operates
• a new user of this particular brand who is struggling with troubleshooting
• an existing user who is trying to upgrade.

The same text might need to cater to everyone, so keep this in mind when writing. However, in some cases, it may be better to write tailored documents for different users.

Put yourself in the user’s shoes. As you write, think about the user’s experience in following your instructions to use a product or go through each step of a process. Make sure you provide the information necessary to complete each step. For example, if various materials will be needed throughout the process, instruct the user to gather them before starting.

Guide your reader with context and clues that they are on the right track – for example, ‘The glue will have dried slightly but will still be tacky. You can now paint the wood’.

Test your instructions on actual users to find what could be clearer and where you may have missed something, made a mistake, or failed to explicitly state an assumption.

See Understanding your users for more information on audiences.

Use straightforward language and tone

The text should be as clear as possible. Keep the vocabulary simple and straightforward, with definitions where they might be helpful. Do not introduce initialisms or acronyms that are not common or necessary. Use the same terminology to refer to the same concepts, items or actions throughout the document, to help your reader to keep things straight.

Be direct and tell the user exactly what to do. With instructions, the imperative voice is appropriate and useful:

The text should also be self-contained; it should include all the information that the reader needs to use a product or follow a process – but no more. Instructional texts are not the place for a lot of background information.

See Clear writing for more information.

Use structure and formatting to guide the reader

Make sure the document’s structure is clear and visible, and leads the reader logically through the steps. Establish the structure during planning by outlining the points your technical document will make, and grouping points logically to create segments or stages. If a particular section is likely to be read as a standalone text (e.g. a recipe in a cookbook), make sure that the text does not rely on earlier references or explanations to make sense.

Formatting can support the structure, with clear design elements that indicate examples, sequential (numbered) steps, introductory information and so on. Separate large blocks of text with headers and graphics, as appropriate. Provide a table of contents and page numbering to assist with navigation to particular parts of the instructions (a reader who wants to know how to change a printer cartridge will not want to read all of the instructions on how to set up the printer for the first time).

See Structure and writing for more information on structuring your content.