6 hours

Document Design

If you were handed these instructions to perform a search using Google, how would you react? Look at figure 3.1. Scroll your mouse over the document to see why it is difficult to read. Then, click on the pop-up link below to describe how you would format these instructions.

Figure 3.1

Search Instructions

General search instructions 1

To perform a general search, the user can enter a term into the Google Search bar, such as "quilts." 2 All Web pages that have the word "quilts" will be returned. The search can be expanded by using the word "or" in searching. 2 For example, using "quilts or blankets" will return all of the Web pages that have either "quilts" or "blankets" on the page. 3

Limiting a search 1

Similarly, a Web search can be limited by using the word "and" as part of the search term. If a user enters "quilts and blankets," only those Web pages that contain both the word "quilts" and the word "blankets" will be returned. 3 Note: Users can enter a plus sign (+) in place of "and" to narrow a search. For example, they can enter "quilts + blankets." 4

Users can also limit a search by using quotes around a search phrase, as in "antique quilts." This has the same effect as adding an "and" in between the two words. 3 Note: Google automatically places the word "and" between two or more terms in the Search bar. For example, antique quilts will be treated like "antique and quilts." 4

If your technical writing is not visually appealing, your intended audience may not even read it. Think of the time and money wasted if your coworkers fail to look at your documents. Such situations can lead to equipment failure, lost work hours, injuries, and, in severe cases, lawsuits.

Readers are often distracted while perusing technical documents; they may skim a paper while jotting down ideas, talking on the phone, or presenting ideas at a meeting. Effective page design can help your readers find the information they need quickly. Elements of page design to help you organize your writing include

white space

lists

headings

font treatments

graphics

We explain each of these below.

White Space

What is white space? It is the spacing between paragraphs and the margins around text and graphics. Your eyes need a break when you read, and white space is important for separating pieces of information. Use paragraphs to cluster similar ideas. Break up your text to help your readers distinguish among topics such as materials, goals, costs, criteria, etc. and to visually "chunk" data for audience.

Lists

Lists can also help break up information for your readers. Scanning a list of items is much easier than reading the items horizontally, separated by commas. Employ lists for supplies, prices, steps, etc. If the reader should follow directions in a strict order, number those directions. If the reader has different options or if the directions are not absolutely required, bullet those items.

All items in a list must be parallel. This means that each item needs to have the same grammatical structure. If you begin a series with a verb, use verbs throughout the series. Avoid mixing phrases and sentences. Test your knowledge of parallel grammatical structure in figure 3.2.

Figure 3.2

Parallel Structure

All lists need to be introduced with a lead-in or a header. For example, if you were writing instructions for baking a cake, you wouldn't scribble the names of the ingredients and the utensils required to perform the activity in the same space. You would list the food items to make the cake under the header INGREDIENTS, and the cooking materials under the header UTENSILS.

Use an introductory clause to introduce lists in-text. For example, if you were citing ways to improve customer service in an e-mail message to your coworkers, you would not start with a bulleted list of ideas. You would introduce the list with a clause. For example instead of stating the following:

Sara, we can improve productivity.

decrease overtime hours

drop our Acme account

hire an additional salesperson

You would create a lead-in:

To improve productivity, I propose that we

decrease overtime hours

drop our Acme account

hire an additional salesperson

If you are writing an introductory clause that ends with a noun or a phrase such as "the following," place a colon at the end of that clause. If the clause ends on a preposition (such as "with" or "in"), do not use a colon. A good rule of thumb is to avoid using a colon if the introductory clause flows into any one of the bullet points so as to form a complete, uninterrupted sentence.

No colon is needed for this type of list:

His painting included

the sand

seagulls

the waves

A colon is needed here:

His painting included the following:

the sand

seagulls

the waves

Headings

Headings are important in creating a visually appealing document. A sans serif font (such as Arial) works well. Use headings to separate major sections and subsections of a document. You can use different heading levels. Just be sure to make the heading styles consistent in size and style.

Font Treatments

Font treatments such as bolding, capitalizing, underlining, and italicizing are an additional means of breaking up information for your readers. Use font treatments selectively; too much of any type of treatment will overwhelm your readers and undermine your writing. Using ALL CAPS is a great technique for warnings and danger signs. But too much capitalizing makes it seem as though you are shouting at your readers. Underlining and bolding text will bring attention to specific words and phrases, but too much will make your writing ineffectual. Again, consistency is key. If you bold, italicize, or underline words just to make your writing appear flashy, you will only confuse your audience and look unprofessional.

Graphics

The saying "A picture is worth a thousand words" rings true in technical writing. Consider the layout of most newspapers. Pie graphs, tables, and illustrations break up the text and give readers a break from dense paragraphs. A well-placed and clearly designed graphic can make a technical document more accessible to an audience.

Ideally, you would place graphics, charts, and illustrations right after the paragraph that discusses them. Always number and title your graphics. Refer to them by their number and/or title within the body of your document. If you did not create the graphics yourself, cite where you retrieved them.

Also, be aware that graphics can be misleading. For example, artists can manipulate pie charts so that a wedge that is supposed to show 25 percent might look as large as a 40-percent wedge. Graphics artists can use incomplete sets of data, overemphasizing one factor or minimizing a problem figure. Photographs can also be manipulative, pulling the viewers emotionally in one direction or another. For example, an image of a clear-cut forest can be extremely effective in a bid to stop a company from building a chain store in a woodsy location. However, if the company wanted to set the store in an abandoned lot, this image would delude viewers and provoke unwarranted anger. Strive for accuracy in creating graphics, and consider all aspects of a situation so that your tables and charts show the whole picture.

Instructions

Think about the last time you read instructions. Where did you read them (in the rain while trying to change a tire?) When did you read them (at 11:30 p.m., with a flashlight?) Did you attempt to accomplish a task or to operate a piece of equipment prior to reading the instructions? What type of mood were you in? People who turn to instructions are usually already in a bad mood because they have probably tried the task and have given up completing it without help.

How do you think most people feel about instructions? Many folks dislike reading instructions and, for this reason, you should carefully consider your audience when writing them. Think of your readers' probable background, experience, education, and attitude, as well as the situation in which they are likely to find themselves while reading your instructions. This analysis will help you determine how much detail you need to include, and how to organize your instructions.

Organization

Provide a roadmap for your readers by including an introduction, a body, and a conclusion. Introductions should contain a definition or description of the product or process involved. Instructions for using objects or for putting them together should contain some sort of graphic. State in plain language just how the document will assist your readers. This can be accomplished through the title, i.e., "Installing and Operating the HP PhotoSmart 2610." Your introduction should also include the purpose of the document, a preview of the object or procedure, and your expectations of the readers: "These instructions are written for people with basic computer skills." You may need to include background information if you suspect your readers may be inexperienced.

Next, provide a list of the items your audience will need prior to starting the project or procedure. These may include equipment (such as hammers, drills, and saws), supplies (such as a tape measure or nails), and items to be consumed in the procedure (such as wood, paint, and oil). If the items are difficult to find, provide a list of places where your readers can obtain them. Again, think of your readers' needs. A layperson may require graphics or diagrams to visualize tools, such as a particular type of screwdriver.

Next, provide step-by-step instructions to give your audience a clear idea of what to do and when to do it. These will constitute the main body of the document. Below, we provide additional information on step-by-step instructions. Your conclusion should address maintenance issues or troubleshooting. You may also need to provide a glossary for non-technical audiences. Be sure to include jargon and terms with which your audience may be unfamiliar.

Step-by-Step Instructions

Writing step-by-step instructions is extremely easy. Begin each series of steps with a title, goal statement, or introductory clause as follows:

To place the spare tire onto the car, complete these steps:

Hold the spare tire in front of the wheel studs.

Align the holes in the spare tire with the studs.

Push the spare tire onto the studs.

Thread the four lug nuts onto each of the studs.

You should generally number your steps instead of using bullets or letters. Numbers will help your readers remember which step they are on. However, if you are writing concise instructions to be displayed on a PDA, cell phone, tablet PC, or other portable device, you may use bullets. You may also use bullets, letters, or Roman numerals for substeps.

Be sure to limit the amount of information in each step, and to write each step as a command, using the imperative mode. Write each step as if your audience has just asked, "What do I do now?" State your answer by giving a direct command: "Turn the brass handle to the left." Test your knowledge of the imperative mode in figure 3.3.

Figure 3.3

Imperative Mode

Each step you write should require an action of the reader. Keep in mind that the result of an action is not a step; this information should be included in the same step as the action. Figure 3.4 shows a set of directions. Which numbered items are actually steps? Which numbered items are not steps? What should be done with the numbered items that are not steps?

Figure 3.4

To Hang a Curtain Rod

Using a pencil, mark the spot on the wall where you want the bracket placed.

Use the appropriate drill bit and drill the two anchor holes.

The drill bit should be the right size for the holes you need.

Insert the screws through the bracket, and align them to the anchors.

The screws may slip out of the anchor holes.

Rest the rod in the first bracket and position the second bracket with a spirit level.

The rod should extend two inches past the window.

Think About It 3.2: Instruction Steps - Please go to My Tools -> Self Assessments -> to complete this self assessment.

Notes and Hazard Alerts

Many instructions contain notes and hazard alerts. Where should these items appear in the document? They should be placed both in the introduction and within the step-by-step instructions. Instructions typically include four types of alerts, ranging from least serious to most severe: notes, cautions, warnings, and dangers.

Generally, a note is used to clarify a point within a step of an instruction. This is the lowest level of precaution.

The following is an example of a note:

Loosen the lug nut.

NOTE: If the lug nut will not move, spray it with WD-40.

A caution warns readers of mistakes they might make. Generally, a caution refers to possible equipment damage.

The following is an example of a caution:

Securely fasten the wrench to the lug nut and pull the handle down.

CAUTION: If the wrench is not securely fastened to the lug nut and pressure is applied, you may strip the lug nut.

A warning attempts to protect readers from bodily harm.

The following is an example of a warning:

On a flat surface, extend the jack until the car is approximately 6 to 8 inches off the ground.

WARNING: Do not jack up the car up on a hill. The car can roll off the jack.

A danger is a notice reserved for immediate and severe hazard to the reader or someone else.

The following is an example of a danger:

DANGER: Flammable gas! No smoking or open flames.

You may want to use graphics to draw attention to hazard alerts. Figure 3.5 shows some universally accepted hazard symbols.

Figure 3.5

Hazard Symbols

A skull and crossbones indicates poison or harm from chemicals.

A triangle with a lightening bolt refers to possible electric shock or a live wire.

Three interlocked circles warn of a biohazard.

Source of images: Wikipedia Open Clip Art Library 2006

Graphics are extremely useful for warning readers at all levels about hazards. Font treatments can also be used to emphasize warnings. The more severe the warning, the more eye-catching should be the font treatment. Writing in ALL CAPS in red can indicate warnings and dangers. For less severe warnings, such as cautions or notes, you can bold or italicize the font.

Troubleshooting and Decision Tables

It is often difficult to determine how your audience may misinterpret your instructions. Longer sets of instructions may need troubleshooting sections. A decision table is the best way to organize troubleshooting guides and instructions where a user needs to make a decision, or has a choice. Some problems or symptoms may have more than one cause. Table 3.1 is a typical troubleshooting table.

Table 3.1

Decision Table

Symptom

Cause

Solution

The scanner will not turn on.

The USB cord is not correctly installed.

Verify that the USB cord is correctly plugged into the back of the scanner and computer.

The scanner is on, but won't scan the document.

You are not properly accessing the scanner.

Open the scanner program from your computer and choose the "Scan" option. If this does not work, try pressing the scan button on the front center of the scanner.

The computer has frozen.

Restart the computer by depressing CTRL, ALT, and DELETE simultaneously.

Your computer does not recognize the scanner.

The software is not properly installed.

Uninstall the software, power down the machine, restart the machine, and reinstall the software.

The USB cord is not correctly connected.

Verify that the USB cord is correctly connected. If it is, unplug the USB cord from the computer, turn the computer off, plug the USB cord back into the computer, and turn the computer back on.

References

Wikipedia. (2006). Hazard Symbols. Accessed May 2006 from http://en.wikipedia.org/wiki/Open_Clip_Art_Library

Report broken links or any other problems on this page.

Copyright © by University of Maryland University College.