Instructional Documentation

COMP3040 > Back to Chapter Topics

Introduction

There are many things to consider when writing instructional documentation. Audience, formatting, use of images, and appropriate definition of terms are just a few considerations - some of which should be determined before writing begins, some of which will become obvious as you are writing. This article will briefly outline some of the above points, and hopefully provide you with some insight into writing helpful instructions.

|...by students = Several times I've had to use really poor instructions, and found it very frustrating. Those instructions that are not well organized or don't give you meaningful information are a waste of time. Having been forced to these poor instructions, I have learned what not to do in my own writing. }}

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.

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 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.

Catering to Different Audiences

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.

Formatting

Simplicity

You may notice that more and more instructional documentation is being formatted to look very plain and simple. The Firefox help documentation, for example, uses only one font colour. Just remember that your readers are not interested in being blown away by flashy colours and diagrams - they just want to find out as quickly as possible how to do something, and move on. Decide on a format that will split the documentation up into tasks. It's a good idea to use specially formatted descriptive headers to make it easier to find tasks:

HEADER


Subheader
This section will describe the steps to...

Subheader
This section will describe the steps to...

Having a knowledge resource that allows readers to quickly find the information they are looking for is more important than having a visually exciting document.

Numbered Lists

One of the most important formatting principles of creating instructions is the numbered list. You should consistently break instruction sequences up into lists of numbered steps, even for short instructions of only two or three steps:

1. Do this

2. Then do this

3. Finally, do this

This not only makes the instructions easier to follow, but it makes it easy for a reader to quickly find where the step-by-step instructions are that will help them accomplish a task.

Define Important Terms

Don't forget to consistently define important terms and make their definitions accessible where they are needed (where the terms are used). It's usually a good idea to have a separate glossary page with all definitions, and then add references to them in the relevant articles. Whether you also define the term on the spot, where the term is used in the instructions, depends on whether you are writing electronic or paper instructions. With electronic instructions, you may just want to add a hyperlink to the glossary for less important terms. Just remember - it's better to define too many terms than to define too few, and force the reader to consult other sources just to understand your instructions.

Repeating Steps

Don't be afraid to repeat common steps (such as Click Tools > options) if they're relatively short or important. You don't want to force the reader to jump all over the place by adding several references to different sections. Even for web-based documentation where the user can just click a hyperlink, 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. Knowing what needs to be repeated and what can simply be stated once will depend on the type of documentation, and will become apparent as you come closer to finishing the documentation.

Images

Where to use Images

While an image may not always be worth a thousand words, it's often worth more than the number of words that take up the same amount of space on the page. Images make it easier to describe things that are difficult to explain in words, and they also serve as visual feedback, reassuring the reader that they are doing things properly. 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 necessary 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 out unnecessary details saves space and shows the reader only those details that they are concerned with. Generally speaking, a nice flow is created by starting off with a full screenshot at the beginning of an article, followed by smaller and smaller screenshots that depict specific actions, if necessary:

1. Click on Edit > Colors



2. Click on Define Custom Colors



3. Enter Red, Green, and Blue pigments

Conclusion

The topics touched upon in this article are just a few of the points to consider when writing useful help documentation. If you take care to consider your audience, use simple formatting, define important terms, and use images where appropriate, then you will be well on your way to writing easy-to-use instructional documentation.

Resources

• Technical Writing Textbook
• Online Technical Writing: Instructions
• Instructions: How to Write for Busy, Grouchy People