WritersUA - Training and Information for User Assistance Professionals

Ten Tips for Tasks: Best Practices for Writing Effective Procedures and Instruction Sets

By Leah Guren, Cow TC

Bookmark and Share


Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Synopsis    Link to contents

Users have come to expect task-based documentation instead of descriptions of product features. They want to know how to accomplish goals, rather than understand the meaning of individual interface elements, isolated from a meaningful user workflow.

Writing procedures therefore deserves time, thought, and careful analysis. Following to these best practices throughout the process helps TCs (technical communicators) create procedures that are more useful, easier to follow, and that better support of the needs of the audience.

The Need for Procedures    Link to contents

From our earliest school days through university, we are exposed to reading material as part of the education process. This material (text books, worksheets, journal articles, etc.) is usually designed to support a classroom activity and to help students learn content. It is referred to as read-to-learn content. But once out of school and able to select our own reading material, most of us only read technical content when we need to solving a problem. This material (user guides, quick starts, installation manuals, etc.) is usually designed to help people use a product safely and effectively. It is referred to as read-to-do content; that is, we read it to figure out how to accomplish a task, not to gain general knowledge.

The problem:
Many years ago, it was a common approach to try to teach the user about the interface. For example, users of CLI (command-line interface) products had to learn cryptic syntax to be able to use the product. Therefore, the job of the TC was to bring the user closer to the product. But in today's world, products are far more intuitive and accessible. We have moved towards a user-centric approach to product design. GUI applications embed text to remove the necessity of memorizing commands, and electronic products have a more natural (even ergonomic) interface; it is as if the product has been brought closer to the user.

So today's user expects task-based information and demands more intuitive product interfaces. Add to this shorter attention spans, increased job complexity, and an overwhelming sea of technology, tools, and information, and you can really understand the need for good, clear procedures! Today's users are not willing to invest time to learn; they just want to get things done.

The solution:
Procedures (also known as step-by-step instructions, cookbook documentation, or instruction sets), provide the right information at the right time, helping the user get to the end goal quickly and efficiently with the minimum amount of background knowledge. Further, they match the user's mental model of documentation, answering the question, "How do I?"

The Jigsaw Puzzle Theory    Link to contents

Unfortunately, just as a good procedure can help a user easily succeed, a poorly-written procedure can lead to frustration and failure. I've analyzed the three most common causes for procedure failure. These problems can be compared to the process of trying to complete a complex and faulty jigsaw puzzle, so I call this the Jigsaw Puzzle Theory:

  • No picture on the box. There is no clear explanation of the purpose or motivation for the task.
  • Missing pieces. Information, often entire steps, is left out.
  • Extra pieces. Information that is unnecessary to the task confuses and distracts the user.

The Ten Tips    Link to contents

By following these ten tips, you can avoid the Jigsaw Puzzle problems while improving customer satisfaction with your documentation.

#1: Analyze Your Audience

Audience analysis is always important, but it is even more critical with procedures. This is the first step for creating task-based documentation. Who are our readers? What are their demographics? What is their technical knowledge? What is their product knowledge? What are their language skills? Where and how are they using the product?

Strategies: Use in-house resources, such as field service technicians, tech support, and Help Desk staff. These people have direct contact with users and can provide you with useful insights. Try getting information directly from users through online or phone surveys (or even better, direct contact). Finally, create personas for each key audience type.

#2: Target (focus on) Tasks

A significant challenge for us as TCs is to translate random features into meaningful tasks. To do this, we need to understand what our users do with the product (both what they want to do and what they need to do). It helps to understand their workflow.

Strategies: Brainstorm! There is no substitute for a concentrated brainstorming session, preferably with other writers or product team members. This should be a casual exercise, such as over lunch. One person should take notes, recording all of the ideas. No one should judge or critique anyone's idea. Afterward, you can combine similar concepts, reject inappropriate tasks, and begin to arrange the results into a logical order. Make sure to name the tasks in a way that is meaningful to the users, preferably in gerund form. For example, Attaching a Sensor to a Cow is better than Using the SensoMatic. Avoid "How to" as it creates concordance in the table of contents (that is, creates too many similarly-named tasks and makes it difficult for readers locate information).

#3: Signify Through Structure

A good procedure is structured information, not blocks of text. Users quickly let their eyes skim over large blocks of text, often missing critical detail.

Strategies: Use clear formatting cues, such as numbers with hanging indents for steps, and consistent repetition for layered information, notes, tips, etc. When designing the layout, always keep the users in mind, particularly where and how they use the product. Make sure that the visual presentation of the information is appropriate for the media and comfortable to use.

#4: Walk Through the 'Why'

Some procedures are quite obvious; others require some explanation to give users the motivation to perform the task.

Strategies: Wrie a sentence or two as an introduction directly after the procedure title. This is your chance to explain what the procedure is for, why or when users need to do it, and also to distinguish between similarly-named procedures. (Would you, for example, know the difference between Removing a Subscriber and Deleting a Subscriber?) In such cases, provide clarification and cross-references. For example, "This procedure removes a subscriber's access while retaining the relevant records in the system database, so that the subscriber can be reconnected later. To completely delete all of a subscriber's records from the system, see Deleting a Subscriber, p. 43."

#5: Present Prerequisites

Can you imagine being halfway through a complicated recipe and suddenly being directed to add something that wasn't listed in the ingredients? Prevent user frustration and task failure by carefully listing all real prerequisites for the task after the introduction.

Strategies: Brainstorm: tools, information, materials, time, work space, protective clothing, previous tasks, and system privileges are a few ideas. Do not list the obvious, such as the computer. Think of a cookbook-a recipe does not tell you that you need a stove, an oven, a sink, or clean counter space! It does, however, list any special or unusual tools.

#6: Smooth out Steps

Steps are the main part of the procedure. We all know how to write clear, short imperative statements, but we sometimes fail to edit the steps to make them absolutely clear and unambiguous.

Strategies: Deciding how to chunk the information is always difficult. What is a single step for an advanced user may require finer chunking (that is, more steps) for a novice. Follow the 'chew-and-swallow' rule to determine which actions go together; that is, actions that logically go together should be kept together (for example, "Select the expiration date and click OK.") Make sure that you yourself can perform the step; you can't write about it clearly if you don't know how to do it! Finally, limit the number of steps. Long procedures have a higher failure rate simply because users tend to lose their place and accidentally skip steps. Solve this problem by using subheadings for logical sections of the overall task, restarting the numbering at 1 in each section.

#7: Layer Levels

Minimalist documentation can be very frustrating, because it assumes that everyone needs the lack of detail. Also, stating the blatantly obvious in a step ("enter your name in the Name field") is a waste of time.

Strategies: Go beyond the obvious. Give the user extra information in the form of layered text (that is, less visually-prominent text that sits under the main step). This can include clarification, more details to help novice users, advanced tips for experienced users, etc. Using the previous example, this could mean telling users the length of the field, if any characters are not allowed, how the field is used by the application, etc. Make sure that you use consistent visual cues that will allow users to skip over this extra info if they don't need it, and to actively seek it if they want more details.

#8: Highlight Hazards

Alerting users to potential problems is a key role for TCs. And when do problems occur? When the user is actually doing something; that is, during procedures.

Strategies: Look for hidden hazards. Look for clues in the information you receive from SMEs. Ask scenario-based questions ("What will happen if") to determine the actual ramifications of an action. Once you have identified hazards, classify them. Don't confuse the user with ten different signal words; no one notices the difference between Caution and Warning, even if it is spelled out somewhere in the document. Start the hazard text with a clear 'do' or 'do not' statement (that is, exactly what the user has to do or avoid). If necessary, explain why. In some cases, you may need to include a work-around in case the hazard was ignored. Finally, place the hazard appropriately; it needs to be directly before the potentially hazardous action.

#9: Get Graphic

Many tasks require graphics to help explain the actions. When we document a physical task (installing a piece of hardware, removing the batteries from a camera, etc.), a graphic is essential. It can simplify and reduce the text, while providing users with clear orientation and confirmation.

Strategies: Decide if you really need a graphic. A screen grab of a simple dialog box is usually not needed, while a line drawing with direction arrows can mean the difference between success and failure when trying to assemble a child's bicycle! Position the graphic with clear proximity to the action, and annotate it to focus the reader's attention.

Developing your visual literacy is a worthwhile investment, as more companies are producing product procedures with almost no text.

#10: Test, Test, Test!

Our responsibility does not end with a draft procedure. Documentation usability testing lets us refine, correct, and clarify.

Strategies: Identify which procedures need testing. Focus on those that were long, complex, or very difficult to write. If this is a new version of an existing product, talk to technical support and find out which tasks in the previous version caused problems. Find testers who match your audience. You can use in-house resources, as long as they are not overly familiar with the product. Provide your draft copy of the procedure with the product, and have the tester think out loud while attempting to complete the task. You can often spot Jigsaw Puzzle problems, such as places where you assumed knowledge, accidentally left out a step, or interrupted the flow with unnecessary detail. Based on your observations, you can go back and refine the procedures.

What Others Say About Leah's Ten Tips    Link to contents

"This session was excellent. Lots of good meaty info encapsulated very well and delivered with lots of anchors to help retain the details."

References    Link to contents

  • Alan Cooper, The Inmates Are Running the Asylum, 2004
  • Don't Make Me Read
  • Janice C. 'Ginny' Redish, Developing and Using Personas and Scenarios (STC workshop)
  • Jean-luc Dumont, Effective Page Layout for the Nonartist (STC presentation)
  • Leah Guren, Signposting, (STC presentation and webinar)
  • Jonathan Price and Henry Korman, How to Communication Technical Information: a Handbook of Hardware and Software Documentation, 1993, Addison-Wesley Professional
  • William Horton, stats on user failure with long procedures
  • Leah Guren, Highlighting Hazards (STC presentation and webinar)
  • Patrick Hofmann, Visual Literacy (STC presentation)
  • Leah Guren, The ABCs of Documentation Usability Testing (STC presentation and webinar)

Leah Guren is the owner/operator of Cow TC. She has been active in the field of technical communication since 1980 as a writer, manager, Help author, and consultant. She now devotes her time to consulting and teaching courses and seminars in technical communication, primarily in Israel and Europe, as well as several certificate courses for STC (Society for Technical Communication). Her clients include some of the top hi-tech companies internationally, including Intel, IBM, and Microsoft.

If you have any questions please contact: leah@cowtc.com


Copyright © 2011 WritersUA. All Rights Reserved.
shannonm *at* writersua *dot* com


The Conference for Software User Assistance

'Developing User Assistance for Mobile Apps' by Joe Welinske

UI Text Design

WritersUA offers cutting-edge training and information to Technical Writers, Information Analysts and Architects, Documentation Designers, Help Authors, Publication Managers, Documentation Leads, Senior Writers and Documentation Contractors, and User Education Specialists. The focus is on software user assistance, which encompasses writing, editing, planning, coding, indexing, testing, programming, localization, and standards development.

WritersUA Home Page First Time Here Contact Us Join Our Mailing List OASIS Member RSS Resource Directory Tools Contractors Training Articles Blogs Web Resources