Today, we’re going to cover five tips for writing online instructions. These tips also apply to online tutorials and other how-to material.
Important Note: The following tips are for general, unregulated instructions. If you are writing, editing, or publishing instructions for regulated products, services, or activities, contact your legal advisor to ensure that your instructions meet safety and disclosure requirements.
1. Separate setup information from the introduction.
Ensure that your readers are aware of important setup information before they begin following your instructions. Setup information includes
- safety warnings and disclaimers;
- required equipment and supplies;
- limitations (e.g., “This tutorial applies to Word 2016 for Mac.”); and
- links to supplementary material that your readers may want to review before following the instructions.
Some of your readers will skip your introduction (that’s just human nature), so use one or more visual cues to separate important setup information from introductory material. Visual cues include
- headings and bold inline subheadings (such as the “Important Note” inline subheading above);
- colored text boxes;
- graphics (e.g., caution symbols, small icon-style images); and
- font changes.
2. Use parallel structure for all steps.
Parallel structure is the gold standard for instruction writing. Parallel structure means that each item in a set (in this case, all of the steps in your instructions) feature the same type of construction. Although there are several ways to create parallel structure, it normally involves writing each item as a complete sentence or phrase using the same tense and starting with the same type of word.
For instructions, this typically means starting each step with a regular verb that tells your readers what action should be taken, such as the regular verbs opening the five tips in this blog post: provide, use, format, insert, and include.
3. Insert graphics below the step.
Most web pages are structured for top-to-bottom scrolling, so insert step-specific graphics below the step so your readers can read the step, scroll down to the related graphics, and then continue scrolling down to the next step.
Depending on the size of your graphics, you may be able to insert them beside the step rather than below; however, if you insert graphics beside the step, ensure that the graphics will move below the step when the instructions are resized for smaller mobile devices.
See “How to Use Track Changes in Microsoft Word” for an example of step-specific graphics positioned below the step.
4. Include supplementary information with the step.
Important supplementary information related to a specific step should appear with the step rather than in the introduction or conclusion because some of your readers will only read the steps. Important supplementary information includes
- links to highly relevant outside help (such as a video demonstrating that step);
- an expanded description of the step; or
- an explanation of the step’s relationship to the previous or next step.
However, use discretion when including supplementary information because too much extra material can become distracting.
Of course, some step-specific information such as safety warnings and disclaimers should appear in the introduction and with the step! (As noted above, contact your legal advisor to ensure that instructions for regulated products, services, or activities meet all legal requirements.)
5. Format steps or sections as numbered headings.
If your steps precede supplemental information (as each of the steps in this blog post do), format the steps as numbered HTML headings. As an example, here is the HTML code for three numbered steps formatted as H2 headings:
<h2>1. Insert Part A into Part B.</h2>
Supplemental information
<h2>2. Glue Part C to Part B.</h2>
Supplemental information
<h2>3. Screw Part D to Part C.</h2>
Supplemental information
Numbering provides your readers with progress guideposts, while HTML heading formats create visual structure in long, scrolling web pages that may otherwise feel overwhelming. As a bonus, HTML headings help search engines, such as Google, understand what your instructions are about, so they may also have a positive effect on your SEO.
HTML headings are meant to head related blocks of content, so don’t format your steps as headings if they stand alone rather than preceding supplemental information. Instead, consider breaking long lists of steps into sections, with each section preceded by an HTML heading:
<h2>Introduction</h2>
Introductory information
<h2>Section One</h2>
1. Step …
2. Step …
3. Step …
<h2>Section Two</h2>
4. Step …
5. Step …
6. Step …
<h2>Conclusion</h2>
Closing information
My next post will outline the steps for finding and replacing special characters in Microsoft Word. (And yes, that post will feature the instruction-writing tips from this post!)