Revision as of 22:26, 6 April 2008

Introduction

Audience

It's important to determine your audience before you begin writing. You will often need to cater to multiple audiences of different technical backgrounds and different levels of knowledge on the topic.

One way of catering to audiences with varying knowledge levels is to put different types of points into specially formatted sections. A common design choice is to separate points that are not specifically numbered steps into sections marked as "Warning", "Note", or "Tip". These separated sections may be inline with the text or off to the side, depending on their importance and on how you decide to format your instructions. This clear separation not only makes the purpose of the instruction clear, but allows readers to quickly scan your document and ignore those points that don't concern them. Someone who's already quite knowledgeable on the subject, for example, may just ignore all the "Tip" sections.

Knowing Your Audience

Knowing who your target audience is will help you determine, for example, what terms require an explicit definition (such as a glossary entry). These kinds of decisions can be difficult, so it's often helpful to try place yourself in the reader's shoes and imagine think about when you learned what the term means. Ask yourself what level of knowledge you had on the subject when you learned the meaning of the term, and make an educated guess as to whether your audience will have that same level of knowledge on the subject. This same method can be applied to other writing decisions, such as how many steps an instruction should be broken down into, and how descriptive each step is.

Define Important Terms

Define important terms and make their definitions accessible where they are needed (where the terms are used). This ties into knowing your audience, and knowing what terms need clarification.

Repeating Steps

Don't be afraid to repeat common steps (such as Click Tools > options) if they're relatively short. You don't want to force the reader to jump all over the place, following references to common steps. Even for web-based documentation where you can use hyperlinks, readers will get frustrated if they have to go back and forth.

On other hand you don't want fifty pages of documentation that could be written in ten pages. Tasks with a common set of initial steps can be grouped in the same section, with the initial steps described once at the beginning of the section.

Images

How extensively you use images depends on the type of documentation. Obviously, instructions on how to assemble a piece of furniture will strongly rely on images to convey the appropriate actions, whereas instructions on making good oral presentations won't require as many images.

Screenshots

It's important to consider context when inserting screenshots. Sometimes it's necesssary to show the entire screen, other times you will only want to show a small section of the screen where the user will be performing the required actions. Cropping unnecessary stuff saves space and allows the reader to just see what they care about. Sometimes you will need to show the entire screen to give context.

Resources

• Technical Writing Textbook
• Online Technical Writing: Instructions