Guidelines for Developing Instructions, Chapter 7 – Nelson and Haupt

The authors present a concise style guide in Chapter 7. Recognizing that there are many possible variations in style, Inaba, Parsons, and Smillie “suggest you use the specifications in a flexible manner and try not to adhere to them rigidly or unthinkingly.

The text offers guidelines for the use of Headings, Command Steps, Sequence of Tasks and Steps, Callouts in Text, Subprocedures (Procedures within Procedures), Table to Supplement Instructions, and Guidance and Routing Information (Notes)

The reference to ANSI standards on page 80 is particularly helpful. The two main ISO/quality organizations in the United States are ANSI and ASQC. The American National Standards Institute (ANSI) is the United States representative to the International Standards Organization (ISO). The American Society for Quality Control (ASQC) is an organization that develops, promotes, and applies quality-related information and technology for the private, government, and academic sectors.

Adherence to official and de facto standards is critical in technical communication. There are a multitude of national and international standards-setting bodies in addition to ANSI and ASQC. For example, The IEEE, a non-profit organization, is the world's leading professional association for the advancement of technology. The full name of the IEEE is the Institute of Electrical and Electronics Engineers, Inc. It is the IEEE that sets many of the standards that today’s computer systems utilize. For example: 802.3 (Ethernet), 802.5 (Token Ring), 802.11 (b) and (g) (Wireless Ethernet).

Due to the existence of numerous standards bodies and the potential for conflicting quality standards, the ISO created a set of five (9000-9004) standards developed to help harmonize the large number of national and international quality system standards. The ISO standards (conformance models) are themselves a subset (in the United States) of the Malcolm Baldridge National Quality Award Criteria. Gaining a working knowledge of standards applicable to the technologies you are working with is invaluable. As you gain an understanding of the standards, you will yourself become technical, and will be able to converse intelligently with the engineers involved in your documentation projects.

Following is a comprehensive listing of the rules Inaba, Parson, and Smillie suggest technical writers use when creating documentation:

• Use distinct, obvious headings to help the user quickly identify and locate the instructions, as well as all of the sections or parts of the instructions.


• Place headings that identify jobs or tasks flush with left margin.


• Place headings for Notes, Cautions, and Warnings in the center of the column


• Use consistent amount of space between heading and subsequent text (e.g. double space).


• Set all headings in bold with consistent use of upper and lower case.


• When instructions exceed one page, repeat task headings at the top of each page.


• To compose titles for tasks and task sequences (e.g., jobs) use the command form of an action verb or verbs followed by the name of the system, equipment, or other objects of the action.


• Use a simple, fixed syntax for command statements. Use a transitive verb (one taking an object) from the command verb list, followed by one or two objects.


• In necessary, modify verb or object with one or two prepositional phrases of a dependent clause. Place such phrases after the basic command.


• Use conditional phrases and clauses to tell how, when, or where to accomplish the work. Please such conditional phrases and clauses before the basic command.


• When the actions are identical for a number of clearly related items treat the entire set as a single action.


• Use fixed set of nomenclature for objects of action verbs.


• Use a maximum of three obviously related actions per step unless a fourth action is needed to bring the step to a close.


• If a single action produces a clear and specific result, and requires more than 30 seconds to perform, present it as a separate step.


• Limit the total number of words in a step to 25, except when additional words are presented in list form.


• Use only one command verb per sentence, unless two verbs are needed to express alternate actions or actions taken close together in time.


• When a command sentence requires more than two objects, present the objects in list form following a colon. If the list is greater than four, partition the list into groups with no more than four objects in a group.


• Assign an Arabic number to each step. Assign 1 to the first step in each task and assign numbers in proper counting sequence to the subsequent steps.


• Arrange tasks and steps in a task in the most likely order of occurrence.


• Incorporate instructions for the use of special tools or test equipment in the sequence if the use occurs only once or twice throughout the entire set of instructions, and no special skill is required to use them.


• When extensive routing is involved within a task (e.g., from two or more steps), provide a routing page that serves as a road map for the user and supplements or is supplemented by the detailed instructions.


• Place the appropriate callout number in parentheses immediately following the name of the equipment.


• When there are two or more like items on the graphic, use two or more callout numbers with a single noun.


• As an option use a subprocedure when a short sequence has a clear and specific result, is needed as part of different tasks, but is not long enough to merit being treated as a task. Compose the title as a step, add “as follows:” and list the action.


• Use tables in combination with command steps when they help clarify instructions. Tables are useful when combinations of events or equipment are involved.


• When using a table for routing purposes, insert the table immediately after the step and on the same page (or facing page) as the step.


• When a large table is needed to support steps on several pages provide the fable on a foldout page that the user can pull out and use together with the instructional pages.


• Assign numbers to tables when two or more tables appear on a page or on facing pages.


• When using a table with a graphic to show the location and function of a number of similar items such as fuses and circuit breakers use callout number to link the items in the table to the graphic.


• Use Notes to provide guidance information and to route the user to the appropriate instructions.


• Always precede safety information with a Caution, Warning, or Danger heading, preceded by the safety alert symbol. Use multiple paragraphs if information exceeds 25 words or covers different subjects.


• Place safety information entirely on the same page as the command step to which it applies. If this is not possible due to the length of the safety information or the length of the step, place the safety information on a separate page preceding the command step.\


• Always place a safety alert symbol and a signal word immediately before the command step to which it applies.


• If Danger or Warning and caution apply to the same step, present the Danger or Warning before the Caution. If a Note is needed, place the Note after the Caution or Warning.


• Use the same style of heading as the style chosen for the planning page. Place the heading in the center of the column.


• Provide explanations for the Warning or Caution, after the primary safety sentence.


• For Cautions and Warnings, use strong terms.


• Whenever a serious situation is implied write the primary safety sentence in command language.


• When a Caution or Warning applies to two or more steps start the statement with a phrase to that effect.


• Always place guidance Notes before the command steps to which they apply.


• Present the routing information as a separate paragraph, separated from the preceding step by an empty space and with each alternate route in a separate paragraph.


• Whenever possible shorten the description of the second alternative when it is the direct opposite of the first.


• To help alert the user, include a phrase in the routing statement to describe the work to be done.


• When directing the user to a step preceded by a Warning, Caution, or Danger signal word, or a Note, instruct the user to read the applicable information.


• If the same obvious alternative applies to a series of steps place the routing statement before the applicable step.