Chapter 18: Instructions and User Guides

Objectives

Upon completion of this chapter, readers will be able to do the following:

1. Analyze and evaluate technical instructions and user guides for effectiveness, considering structure, clarity, format, and audience appropriateness.
2. Write clear, accurate, and ethical instructions using effective style, formatting, and design principles like headings, lists, special notices, and graphics.
3. Develop and structure instruction manuals and user guides with appropriate components, including introductions, equipment lists, step-by-step procedures, and conclusions.
4. Apply audience analysis and task orientation to create user-centered instructions that match readers’ knowledge and needs.
5. Explain and implement the documentation process for user guides, including planning, prototyping, usability testing, revision cycles, and production documentation.

Introduction

Technical writing is commonly used to create instructions, which are step-by-step explanations of how to perform actions like assembling, operating, repairing, or maintaining something. For a document that seemingly should be easy and intuitive to create, instructions are oftentimes poorly executed and far from user friendly. You may have experienced an infuriating situation, in part, because of poorly written instructions. What follows in this chapter will demonstrate what professionals consider the best techniques in written instructions.

Ultimately, good instruction writing requires:

• Clear, concise writing
• A thorough understanding of the procedure in all its technical detail
• Your ability to put yourself in the reader’s place, the person trying to use your instructions
• Your ability to visualize the procedure in detail and to capture that awareness on paper
• Finally, your willingness to test your instructions on the kind of person you wrote them for.

This chapter explores some of the features of instructions that can make them more complex. You can in turn use these considerations to plan your own instructions.

The focus for this chapter is one of the most important of all uses of technical writing—instructions. As you know, instructions are those step-by-step explanations of how to do something: how to build, operate, repair, or maintain things.

Some Preliminaries

At the beginning of any instruction writing project, determine the structure or characteristics of the procedure. Your understanding of the procedure could determine success or failure, or even life and death.

Early in the instruction writing process, define the audience and situation. Recall that defining an audience means defining its level of familiarity with the topic and other pertinent details, including age and ability. See Chapter 24 for more guidance on audience analysis.

If you are in a writing course, you may need to provide a written description of your audience attached to your instructions. That will help your instructor assess whether your instructions are appropriate for the intended audience. In a technical-writing course it is preferable to write for non-specialist audiences—much more of a challenge to you as a writer.

Next, determine the number of tasks in the procedure you’re describing. A procedure is the entire set of activities your instructions discuss. A task is a semi-independent group of actions within a procedure, like setting the clock on a microwave oven.

A simple procedure like changing the oil in a car contains only one task; there are no semi-independent groupings of activities. Within that task are several steps like removing the plug, draining the old oil, replacing the filter, and adding the new oil. If you were writing instructions on maintaining your car yourself to save money, you would have several tasks, some are independent like rotating the tires, checking the fluids, or replacing the windshield wiper blades.

A complex procedure like setting up a new gaming console is another example of a procedure that contains plenty of such semi-independent tasks: setting the clock; setting the power level; using the timer; and cleaning and maintaining the microwave.

Instructions include more than just tasks. Some instructions have only a single task but have many steps within that single task. For example, imagine a set of instructions for assembling a complex LEGO kit such as the popular flower arrangement/bouquet kits. From personal experience, these kits can have over 150 steps! That can be a bit daunting to the user. A good approach is to group similar and related steps into phases and start renumbering the steps at each new phase. A phase is a group of similar steps within a single-task procedure. In the botanical LEGO kit example, setting up each type of flower might be its own phase.

Another consideration, which may be undetermined at first, is how to focus your instructions. For most instructions, you can focus on tasks, or tools (or features of tools). Your approach will depend on your overall objective in writing the instructions; you will find that the task approach is one you will probably use most often, with the discussion of the tools included in notes or supplementary sections like a glossary.

In general, use task orientation for assignments in a technical writing class. Focus on the tasks your readers want to perform; use how to or -ing phrasing on headings.

In a task approach (also known as task orientation) for instructions on setting up your voicemail, you'd include these sections:

These are tasks—the typical things we'd want to do with the machine.

On the other hand, in a tools approach to instructions on using a copy machine, you might find these unlikely sections:

If you designed a set of instructions on this plan, you'd write steps for using each button or feature of the copy machine. Instructions using this approach are hard to make work. Sometimes, the name of the button doesn't match the task it is associated with; you may have to use more than just the one button to accomplish the task. Still, sometimes the tools/feature approach may be preferable.

Finally, decide how you are going to group tasks. Simply listing tasks may not sufficient. If many tasks are required, you must group them to help readers find individual ones easily. For example, the following are common task groupings in instructions:

Common Sections in Instructions

The following is a review of the sections you'll commonly find in instructions.

Figure 1: Schematic view of instructions. This is a typical or common model for the contents and organization; however, many others are possible.

Title

Your title should be concise. Avoid awkwardly descriptive strings like "Amazing Pizza Rolls Baking Instructions." Instead, opt for the "how to" approach, like "How to Clean Your G.E. Microwave" or the gerund, or -ing word phrase, such as "Conserving your Apple iPhone’s battery life."

Date

With technical instructions, the production/version date is a vital piece of information that ensures the reader is operating from the most current instructions, and if they are not, informs them where instructions belong in the line of documents related to this product or procedure.

Table of Contents

If your instructions consist of multiple tasks, has multiple sections, or if they are being presented in the form of a manual, a table of contents is necessary.

Introduction

Carefully plan your instructions’ introduction. Ensure it includes any of the following (but not necessarily in this order) that apply to your instructions:

• Indicates the specific tasks or procedure to be explained and the scope of coverage (what won't be covered).
• Indicates what the audience needs in terms of knowledge and background to understand the instructions. You may also specify audience age here.
• Gives a general idea of the procedure and what it accomplishes. If this is a lengthy set of instructions, indicate how much time may be necessary to complete the task or procedure.
• Indicates the conditions when these instructions should (or should not) be used.
• Gives an overview of the contents of the instructions.

General Warning, Caution, Danger Notices

Instructions should warn readers about potential equipment damage, procedural errors, and accidental self-harm. Also, instructions must often emphasize key points or exceptions. For these situations, you use special notices—note, warning, caution, and danger notices. Typically, the term Danger signifies a risk of severe bodily harm or death. Warning refers to a risk of bodily harm or major damage to the product. Caution alerts the reader to be careful because a risk might exist. Note explains details or troubleshoots a step within a task.

Technical Background or Theory

After the introduction you may need insert background information related to the procedure. This background is critical for certain procedures; otherwise, the steps would be impossible to follow. This is where your expertise in writing technical definitions and descriptions will shine. 

Equipment and Supplies

Most instructions list the tools, equipment, and supplies needed for a procedure. These items may include mixing bowls, spoons, bread pans, hammers, drills, saws, wood, paint, oil, flour, and nails. Instructions usually list these in a simple vertical or two-column list. Use a two-column list if you need to add specifications like brand names, sizes, amounts, types, or model numbers. This may be a good place to use graphics or visuals, especially if a necessary tool is a specialty item.

The Steps

When you begin drafting the steps, keep several things in mind:

• the structure and format of those steps
• supplementary information that might be helpful
• the audience and general writing style

Structure and Format

Normally, we imagine a set of instructions as being formatted in vertical, numbered lists—and most are. Normally, you format your actual step-by-step instructions this way. However, some variations must be considered:

• Fixed-order steps are steps that must be performed in the order presented. For example, if you are changing the oil in a car, draining the oil is a step that must come before putting the new oil. These tasks are numbered lists (usually, vertical numbered lists). When in doubt, structure your instructions in this format. You may then use notes to indicate if there is any leeway to perform the steps in another sequence.
• Variable-order steps are steps that can be performed in practically any order. Good examples are those troubleshooting guides that tell you to "check this, check that" where you are trying to fix something. With this type, the bulleted list is the appropriate format.
• • Alternate steps present two or more ways to accomplish the same thing, or when various conditions exist. Use bulleted lists with “OR” between alternatives, or indicate alternatives with a lead-in.
• Nested steps are complex steps that need to be broken down into smaller steps. In this case, you indent further and sequence the sub-steps as a, b, c, etc.
• "Stepless" instructions cannot use numbered vertical lists and that do little if any straightforward instructional-style directing. Some situations must be so generalized or so variable that steps cannot be stated.

Supplementary Information

Often, simply telling readers to “do this” or “do that” is not enough. They need more detailed information like how the thing should look before and after the step; why they should care about doing this step; what mechanical principle is behind what they are doing; and more micro-level explanation of the step—discussion of the specific actions that make up the step.

The problem with supplementary discussion, however, is that it obscures the actual step. You want the actual step to stand out. There are at least two techniques to avoid this problem: you can split the instruction from the supplement into separate paragraphs; or you can bold the instruction. The example below shows you a possible technique for including supplementary discussion so that it doesn't obscure the instructions.

Bold text helps distinguish the actual action from the supplementary information.

Writing Style

Avoid telegraphic writing—omitting "understood" articles (the, a, an). True, robots write that way, but we don't have to.

The way you actually write instructions, sentence by sentence, may seem contradictory to what previous writing classes have taught you. However, notice how "real-world" instructions are written: They use a lot of imperatives (command, or direct-address) kinds of writing; they use a lot of "you." That's entirely appropriate. You want to get their full attention. For that reason, instruction-style sentences sound like these: "Press the Pause button on the front panel to stop the display temporarily" and a clarifying note might read "You should be careful not to..."

If your instructions have to be more formal, ask your teacher about preferences for using "you." You may find that the direct address isn't appropriate for certain contexts.

For the most effective instructions, begin each step with an action verb.

Never use passive voice in instructions. Some instructions sound like this: "The Pause button should be depressed in order to stop the display temporarily." We wonder who's supposed to depress the thing (are you talking to me?). Or consider this example: "The Timer button is then set to 3:00." Again, as the person following these instructions, you might miss this; you might think it is simply a reference to some existing state, or you might wonder, "Are they talking to me?" Almost as bad is using the third person: "The user should then press the Pause button." Again, it's the old double-take: you look around the room and wonder, "Who me?"

People often omit articles in instructions like "Press Pause button on front panel to stop display of information temporarily" or "Earth person, please provide address of nearest pizza restaurant." Be sure to include all articles (a, an, the) and other such words that we'd normally use in instructions.

Conclusion

A conclusion ties the process up neatly; offers troubleshooting information (i.e. what to do if something went wrong); and, if you are writing the instructions as part of your work responsibility, should include contact information.

Other Back Matter

Your set of instructions may include a list of references, a glossary or appendix, an index, or technical specifications. Items placed here are important to the overall instructions because they provide additional information that certain audiences may need, but that are not critical to understanding how to complete the procedure.

Graphics and Images in Instructions

Graphics are crucial to some instructions. Sometimes, words simply cannot explain the step. Illustrations are often critical to readers' ability to visualize what their steps are. Consider the example of car repair manuals that use photographs to illustrate procedures, or screen shots demonstrating certain software.

In a technical writing course, instructions may require you to include illustrations or other kinds of graphics. Make sure the graphics you use are appropriate, clear, and placed in close proximity to the steps they illustrate.

If you don't create your own graphics or images, and find them in other sources, be sure that you cite the source, preferably right below the graphic. Check with your instructor to make sure you are allowed to source images not created by you. Some technical writing courses require you to create your own images.

Format of Instructions

Read Chapter 29 for more detail about formatting and document design; this section provides a brief overview.

Headings

Use headings in your instructions. Include headings for background sections, equipment and supplies, and the actual instructions section. Use subheadings for individual tasks or phases within the instructions section. Refer to the examples at the beginning of the chapter.

Lists

Lists are used extensively in instructions, 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. In-sentence lists are good whenever you give an overview of things to come.

Special Notices

In instructions, you must alert readers to possible hazards that may damage their equipment, waste supplies, cause procedure failure, or injury to themselves or others—even seriously or fatally. It is imperative to write clear, and direct warnings and special notices for the health and safety of all parties.

Notice how the note is indented to the text of the preceding step.

Notice that the warning (more severe than a note) is placed at the beginning before any of the steps.

Numbers, Abbreviations, and Symbols

Instructions also use numbers, abbreviations, and symbols. Be sure to use them correctly. Remember if your instructions pertain to a brand name product to use trademark symbols appropriately.

Revision Checklist for Instructions

As you reread and revise your instructions, watch out for problems such as the following:

• Provide real instructions—explanations of how to build, operate, or repair something.
• Identify where the instructions will be used.
• Write a good introduction where you indicate the exact procedure to be explained, indicate audience requirements, and provide an overview of contents.
• Make sure to use the various types of lists wherever appropriate. Use numbered vertical lists for sequential steps.
• Use headings to mark off all the main sections and subheadings for subsections. (Remember that no heading "Introduction" is needed between the title and the first paragraph. Remember not to use first-level headings in this assignment; start with the second level.)
• Use special notices as appropriate.
• Make sure you use the style and format for all headings, lists, special notices, and graphics as specified by your teacher for instruction writing assignments.
• Use graphics to illustrate any key actions or objects and make certain they are located right beside or beneath the step they illustrate and properly labeled.
• Provide additional supplementary explanation of the steps as necessary.
• Remember to create a section listing equipment and supplies, if necessary.

Some Final Thoughts about Writing Instructions

As a technical or workplace writer, your ability to write good instructions carries a few ethical implications. Keep in mind that poorly or carelessly designed instructions leave you or your company liable for damages and destroys your credibility and authority. Before you submit any instructions for final review, show them to a colleague. For small or routine procedures, it may be enough to have a coworker look them over, but more complex instructions should always be tested for usability. Make sure that you have read the chapter on Usability Testing and carried out the necessary testing before your instructions go to publication and distribution.

User Guides

A user guide is essentially a book-length document containing instructions on installing, using, or troubleshooting a hardware or software product. A user guide can be very brief—for example, only 10 or 20 pages or it can be a full-length book of 200 pages or more. While this definition assumes computers, a user guide can provide operating instructions on practically anything—lawnmowers, microwave ovens, dishwashers, and so on.

The more complex the product, the greater the page count. When this happens, some elements of the user guide get split out into their own separate volumes—especially the installation procedures, troubleshooting procedures, and the commands. A user guide can even contain a brief tutorial—for example, getting users started using the product—but if there is too much tutorial, it too goes into a separate book.

Filepad User Guide

Gimp User Guide

Parallels User Guide

Style and Format of User Guides

A user guide is a combination of many things presented in this online textbook. At its core it’s instructions writing, you need to be good at the writing style, headings, lists, notices, highlighting, tables, and graphics commonly used in instructions. As a set of instructions, a user guide should use the style and format that is presented elsewhere in this chapter:

• Headings. Use headings to mark off key contents of the information so that readers can find it quickly.
• Lists. Use numbered and bulleted lists to help readers scan information quickly.
• Special notices. Use special notices such as warnings, cautions, and notes to alert readers to potential problems or emphasize special points.
• Instructional design. In general, use the standard design of instructions; primarily, this means task-oriented headings and sections and numbered vertical lists for actual steps that readers are to perform.

Instructions—and therefore user guides—also make abundant use of:

1. Graphics. Show readers key components of the objects they will be working with, before and after views, and illustrations of key actions that readers must perform.
2. Tables. Provide statistical information and other such details in easy-to-access table form. In user guides, tables are particularly useful whenever reference-type information must be presented.
3. Highlighting. Use a consistent and standard scheme of highlighting (bold, italics, alternate fonts, color, caps, and so on).

Components of User Guides

As a book, a user guide must have some combination of the standard book-design components such as the following:

• Front and back covers
• Title page
• Edition notice
• Trademarks
• Disclaimers
• Warranties
• License agreements
• Safety notices
• Preface
• Appendixes
• Glossary
• Index
• Reader comment form

There is no standard combination or sequence of these elements; every company does it differently. Details on the contents, format, and design of these elements can be found in the book design chapter.

Information Included in User Guides

Here's review the common contents of user guides:

Instructions

The most obvious are those step-by-step directions on how to assemble, operate, or troubleshoot the product. Instructions in user guide should generally be task-oriented—that is, written for specific tasks that users must perform. Instructions should generally use vertical numbered lists for actions that must be performed in a required sequence. Similar or closely related instructions in user guides should be grouped into chapters.

Precautionary Information

You'll see notes, warning, caution, and even danger notices in user guides. These represent liability concerns for the manufacturer of the product.

Reference Information

User guides typically contain plenty of reference information, but only up to a certain point. For example, if there are numerous commands, a separate book for commands is necessary. Reference information in user guides is often presented in tables: columnal lists of settings, descriptions, variables, parameters, flags, and so on.

Getting Started Information

Some user guides will include brief tutorials that will help new users get acquainted with using the product.

About the Product

User guides also provide some description of the product, a review of its essential features or its new features. Sometimes this information also gets put into a separate volume, if it is extensive. Typically, the volume will be called something like "Introducing New Product..."

Technical Background

Sometimes, user guides will include technical explanations of how the product works, what physical or chemical principles are essential to its operation, and more. For example, you will see considerable background in user guides for graphic or audio programs. You can't operate them without understanding the concepts of brightness, saturation, and hue, among other things.

Process and Internal Documents for User Guides

An important part of user guides—in fact, of almost any technical document—is the process that produces it.

Initial Planning

Early planning on a user guide includes a needs assessment (making sure documentation I needed for the guide), an audience analysis (a clear depiction of who will be using the document and assessing their needs), a task analysis (what will the product be used for and what are their common tasks?), a library plan (what books and media, in addition to a user guide, are required to support the product?).

Documentation Proposal

If you are working freelance or as part of an independent documentation firm, you may have to write a documentation proposal to win a technical documentation project.

Documentation Plan

User guides require documentation plans, internal supporting documents that detail project content, audience, design, format, production team, schedule, and other relevant information about project deliverables. The plan resembles the documentation proposal in some ways, but the plan represents an agreed upon plan (that means both the user guide and the product it documents).

Prototype and Specifications

Important planning tools, which also serve as useful reference tools during a documentation project, include the prototype of the user guide and the specifications for the user guide. The prototype is a dummy version of the book with all planned components of the book (see the list on book-design components) and all planned elements (see the list under format and style). However, the prototype uses "greeked" text (also known as Lorem ipsum) like the example shown.

Optional: Learn more about Lorem ipsum.

Typically, the prototype of the user guide is very brief: it needs to include only as many pages as it takes to illustrate every unique textual component and textual element that will be used in the user guide. Specifications are descriptions of a book design in table form. Specifications describe every unique component or element of a book, so that it can be recreated by someone who might not have access to the electronic files, templates, or styles of that book.

Template and Style Catalog

A well-designed user guide, and a well-designed process to produce that user guide, should include templates and style catalogs. A template is an electronic file that defines such aspects of the user guide as page size, headers and footers, page-numbering style, regular and special page layout, and other such detail. A style catalog is also an electronic thing that defines the format and style of textual elements such as headings, headers, footers, lists, paragraphs, tables, and so on. For example, a style for a "heading 1" might specify 24-point Arial bold with 24 picas above and 12 picas below. Styles help you create a user guide more efficiently; styles also help you maintain consistency in the format and style of that user guide.

Multiple Review Drafts & Sign-Off

A good process to produce a user guide also includes several drafts that editors, technical experts, usability testers, and documentation team members can review. You as writer then implement those recommendations and produce a new draft for these same people to review again. When everybody is satisfied with the draft (or out of time), they sign off on the project, which will then go into "production," which means producing the finished bound copies or the PDF that is made available to users.

A user guide covers many topics in this online textbook. If you’re taking a technical writing course, you may not implement all features and phases. Consult your instructor to determine which are required.

Exercises and Activities

Exercise 1: Locate a set of instructions for an item you currently own. How effectively do these instructions meet the guidelines presented in this chapter? Analyze each part of the instructions separately and summarize your findings in a memo to your instructor. Be prepared to share examples with the class if you are in a face-to-face classroom.

Exercise 2: Identify the ethical issues or concerns you must address in creating instructions for the following: installing a water heater; changing the brakes on a car; preparing an elaborate meal for a large group; attaching the wing to a fighter jet (okay, I know...this is pretty obvious); office policies and procedures for new employees. Can you think of other situations in which ethical concerns must be addressed?

Exercise 3:  Create an instruction manual. This may be completed as a group or individual project: Instructions for this activity may be found here. Your teacher will provide additional information and guidelines.

Attribution

This chapter is revised from the first edition of Open Technical Communication, Chapter 2.6: “Instructions” by David McMurrey and Cassandra Race and Chapter 2.7: “User Guides” by David McMurrey and Tamara Powell, which are both openly available under a Creative Commons Attribution license.

The content in Chapters 2.6 and 2.7 of the first edition of Open TC were originally sourced and revised from David McMurrey’s Online Technical Writing, sections titled “Instructions” and “User Guides,” which are both openly available under a Creative Commons Attribution license.

AI Assistance Notice

Some parts of this chapter were brainstormed, drafted, and/or revised in conversation with ChatGPT 4o and Google Gemini 2.5 Flash. All AI-generated content was reviewed and revised as needed by a human author.