10.3 Style, Formatting, & Graphics in Instructions

WRITING STYLE

Sentence by sentence, effective written instructions may seem to contradict what previous writing classes have taught you. But instructions have a very specific purpose and there are explicit writing strategies that serve that purpose. Below are standard sentence style elements for instructions.

Use imperative mood verbs. Speak directly to your reader and offer clear, straightforward commands. “Do this.” Effective instruction sentences sound like these:

  • Press the Pause button on the front panel to temporarily stop the display of information.
  • Insert Part 347 into Part 348 and tighten securely by twisting Part 348 counterclockwise.
  • Tap the Stop icon to stop the recording.

Avoid passive voice. (This applies to all types of writing). Below are examples of passive-voice instructions.

  • The Pause button should be depressed in order to stop the display temporarily.
  • The Timer button is then set to 3:00.

Avoid third-person point of view. Below is an example of what not to do.

  • The user should then press the Pause button.

Do not omit articles. Below are examples of de-articled sentences. Awkward.

  • Press Pause button on front panel to temporarily stop display of information.
  • Earthperson, please provide address of nearest pizza restaurant.

It may seem efficient to cut down the word count of an instruction set by omitting articles, but doing this only makes instructions difficult to follow. Include all articles (a, an, the) and other such words that we normally use.

HEADINGS

As in most technical writing documents, headings and subheadings should be used to indicate the various sections of the instruction set in a logical, coherent order.

LISTS

Instructions typically make heavy use of lists—particularly numbered vertical lists for the actual step-by-step explanations. Simple vertical lists or two-column lists are usually good for the equipment and supplies section.

GRAPHICS

Graphics are crucial for instructions. Sometimes, words simply cannot explain the step. Illustrations are often critical to readers’ ability to visualize what they are supposed to do. Using the principle of proximity, place graphics close to the instruction step to which they refer.

SPECIAL NOTICES: Note, Warning, Caution, Danger

Instructions must alert readers to situations or conditions in which they may damage equipment, waste supplies, botch the procedure, or injure themselves or others—seriously or even fatally. Companies have been sued for lack of these special notices, for poorly written special notices, or for special notices that were out of place. Figure 2, below, shows the four standard special notice types and the situations in which they should be used.

Figure 2. Standard signal warnings and situations requiring their use. Image by UbikwitusThey is licensed CC BY-NC-SA 4.0.

NUMBERS, ABBREVIATIONS, AND SYMBOLS

Instructions use many numbers, abbreviations, and symbols. In technical contexts, we use numerals—even those below 10—in text if they are critical values. In other words, we break the rules that are taught in regular writing courses and that are used in normal publishing and copyediting practice. Most of those writing situations call for writing out numbers 1–10 and using numerals for numbers above ten. But in the technical and scientific context, documents often include large numbers of numbers; we frequently work with statistics and measurements. Using numerals makes sense.

The rules may vary depending on your employer or the particular type of writing you are doing, but there are some conventions that usually apply. You should use numerals, not words, when the number is a key value, an exact measurement value, or both. For example, in the sentence “Our computer backup system uses 4 mm tape,” the numeral is in order. The numeral is also correct in “This recipe calls for 4 cups of unbleached flour.” But consider this one: “There are four key elements that define a desktop publishing system.” A word, not a numeral, is preferable here because the number of elements is exact, but it’s not critical. Someone from a competing company may claim that there are five key elements that define a desktop publishing system. Either way, it’s not a critical issue: the desktop publishing system will still function no matter who claims what about how many elements comprise it. But the number 4 is critical in the two earlier sentences; it is an exact measurement in the recipe and in the tape size.

writing numbers in technical documents

To summarize the rules that we normally apply to writing numbers in technical documents:

  • Don’t start sentences with numerals—write the number out or, better yet, rephrase the sentence so that it doesn’t begin with a number.
  • For decimal values less than 1, add a 0 before the decimal point: for example, .08 should be 0.08.
  • Make a firm decision on how to handle 0 and 1 when they refer to key, exact values and stick with it. Some technical styles choose to use words for these; they resign themselves to the slight inconsistency but better readability.
  • Use numerals for important, exact values, even when those values are below 10.
  • Use words for numerical values that are unimportant, such as in the sentence “There are six data types in the C programming language.”
  • When you must use fractions, avoid the symbols that may be available in the character set used by your software. Construct the fraction like this: 5-1/4. Be sure and put the hyphen between the whole number and the fraction.
  • Stay consistent in using either decimals or fractions. Use one form or the other throughout your document. It would be nice if all fractions could be reset as decimals, but such is not the case when you have things like 1/8 floating around.
  • Don’t make numerical values look more exact than they are. For example, don’t add “.00” to a dollar amount if the the amount is rounded or estimated.
  • Apply these rules in specifically technical, scientific contexts only. Utilize the standard practices for the context in which you are writing.

When using abbreviations in your documents, keep in mind that abbreviations may be useful, but can also be confusing. Use them with caution and be sure your readers will understand them.

As with abbreviations, consider your audience and use symbols carefully to avoid creating confusion.

Effective technical writing is not about impressing your audience with your knowledge of arcane information, symbols, and jargon. It is about making information available to your audience in a way that’s easy for them to understand.