Guidance information is also known as step-by-step instructions how-to instructions, or procedures, and makes up the heart of all task-oriented documentation systems. Procedures consist of a mix of explanations and steps; the job of the designer or writer of these is to balance these elements.
Guidelines
1. Relate the Task to Meaningful Workplace Activities
“A procedure is a step-by-step series of commands for accomplishing a meaningful operation with a software program” (p. 64). The goal of writing a procedure is to see it as a part of larger activities. Procedures are the operation part of the activity/action/operation model examined in Chapter 1. The job of the writer is to clarify how the procedures fit into the larger picture in the user’s workplace.
2. Determine How Much Information Your User Needs
How much information users will need depends on the difficulty of the task, and their experience. Identifying both of these aspects will help the writer decide whether to make the procedure richly detailed or sparse. Layering is “a formatting technique that allows for different levels of information (beginning and advanced) on the same page” (p. 87) and caters to both levels of users and levels of information.
To enrich procedures, consider adding the following:
· Screen shots (show the actual user interface, what menus to display, and what choices to make)
· Cautions and warnings (alerts user to be careful of damaging product, losing data, compromising performance of system, and possible harm to humans as a result of errors with software or equipment)
· Tips for efficient use (suggest alternatives, workaround, and helpful applications; can also elaborate a step or command)
· Tables showing options the user can take with a specific task (organize information and present it efficiently: features and uses, terms and definitions, setting names and options, users and program sections tables of contents; keep tables simple and cite them in the text; use descriptive, performance-based column titles)
· References to other sections of the manual or resources
· Explanations
· Cross-references and links
· Icons
· Graphics showing program concepts
· Keystroke combinations
· Examples
· Footnotes
3. Choose the Appropriate Procedural Format
Choose from standard, prose, or parallel; it is a good idea to stick to one.
· The standard format consists of steps, notes, screens, etc, aligned on the left margin.
Advantages: It is recognizable by users, there is an easy flow from one page to another, it is easy to renumber and test, and it is easy to see the steps using a hanging indent.
Disadvantages: It may occupy a lot of space and maybe confusing if complex and simple steps need to be mixed.
· The prose format includes steps in sentence and paragraph form; a conversational tone occurs in programs with simple tasks and a simple interface. Bold and italics are used for command verbs, function keys, buttons, and text for the user to type in.
Advantages: It is conversational and relaxed in tone, saves space, clarifies simple, basic steps, and accommodates experienced users.
Disadvantages: It buries the steps in paragraphs, precludes lengthy explanations of individual steps, can’t accommodate graphics for individual steps, and doesn’t offer much support for novice users.
· The parallel format is useful for programs that include complicated data fields or dialog boxes and programs that require the user to move from one field on a screen to another, filling in each one along the way. Writers and designers should keep the terminology consistent, cue terms to the screen, discuss one screen at a time, use plenty of examples, and explain to users how the format works.
Advantages: It can help users stay organized, works well with shorter procedures, and is good for filling out complicated screens and dialog boxes.
Disadvantages: It does not present information in a step-by-step, task-oriented manner, can’t be used for all procedures because it is specialized, may confuse the user who gets lost moving between steps and screens, and has to fit on one page.
· For embedded help, a writer working with a programmer put tags into both the program and the help system. It displays procedural information as a part of the interface of the system, and, unlike conventional help, is not a separate program. Embedded help is useful for tips for efficient use; cue cards; short, animated demonstrations; and trouble-shooting tips. Types of embedded help include flyout help, interactive flyout help, do it for me help, field-level help, interface help, pop-up definitions, and roll-overs (p. 79).
4. Follow a Rhythm of Exposition
This means a pattern of step, note, and illustration. First give a command for a step, then say how the program will respond, then illustrate what happened, then tell the next step.
5. Test All Procedures for Accuracy
Test the pacing and format for the desired effect. Perform evaluative tests, where an actual user or prototype of a user actually performs the steps.
Discussion
What Constitutes a Procedure?
“Procedures are often rooted in the features of the software program” (p. 81). But in the office or the business, these features can differ greatly from the uses. The writer or designer should consider the features as the tools the program provides for the user. The procedures result from putting the functions of the program into a usable set of steps that do the user’s work. Procedures usually follow a chronological sequence, with a beginning and an ending. Kinds of guidance information include installation (which is usually accompanied by a wizard, which is the personification of a guide or assistant), maintenance, and repair, but most procedures focus on the actual operation of the program, the day-to-day uses.
How Does a Procedure Work?
The task name identifies the program in performance-oriented language.
The overview serves first as an introduction and describes the use of the procedure. Using informal language, it should prepare the reader to perform the steps, by indicating necessary skills and conditions. Second, the overview directs the user once he or she is started with the procedure.
The steps give the user tools to use and actions to take with the tools. In writing steps, numbers should be used as opposed to bullets, and numbered steps should not include renumbered actions. In notes and explanations commands should be avoided and imperative verbs preferred.
Elaborations comment on the steps as they get performed. They can include possible mistakes and how to avoid them, how to perform procedures efficiently, alternatives (keystrokes, toolbars, function keys), definitions of terms, how to tell if a step was performed correctly, where to look for supplemental information. Elaborations should be phrased in an active voice and should refer to the program.
Options are optional commands or keystrokes and should be presented in a table.
Screens illustrate to the user the tool in use or the goal or results of an action. They can show an overview, a partial result, a final result, dialog boxes, toolbars, and menus.
Dianna Cowles, Robin Erickson, Anna Ignatjeva
11 comments:
This is a very thorough chapter and it brings up things I had not thought about before, such as layering. Many times, this kind of information will be used by experienced AND inexperienced people. Although the writer can speculate about the typical user, it's a good idea to consider a broad range of abilities. Screen shots are a very good way to illustrate facts; experienced users may glance at the illustrations, while inexperienced users may need to pore over them. Either way, their needs are met. Cautions/warnings, tips, and tables of information can serve the same purpose.
I can't remember who it was in class who mentioned all of the typos in this text book. I hadn't noticed them before, but now that I am looking for them, I am noticing them more. On page 78, about midway down the page, the author refers to figure 3.2, but he is actually describing figure 3.15. Pretty basic stuff to mess up. It takes some credibility away from the book.
I wonder how often prose format is used in writing procedures. I would think that technique would be the least helpful. Many users won't take the time to read through a paragraph to find an answer to a question. One of the stated disadvantages is that prose format "doesn't offer much support for novice users," but I would think that more advanced users would be even less inclined to read through a paragraph to find an answer.
I most appreciated Barker's advice regarding steps. This is on page 84 and following. I could relate to the fact that users will skim the steps in their written form. But how many time have you come back to the steps in order to complete procedure. Keeping the steps in logical, sequential, and their most brief order as possible will guide the reader in the most efficient manner possible.
I also found the section on embedded help to be interesting. The concept of embedded help seems to be such a great tool--the information you need at the click of a mouse or a rollover of the curser. So why then are most people not using embedded help? Is it the presentation of the help on the screen? Is it because the embedded help is not written efficiently? I've yet to have someone tell me they really like the "built in" help that is part of a particular program. Seems to me we still have a ways to go with embedded help.
Like Lance, I also appreciated the section on steps. I highly prefer steps over prose when reading procedures for easier scannability when searching for certain steps. I understand the reasons for not renumbering steps, but why not use a, b, c... like an outline? There was no mention of this, so I wonder if there is a reason to avoid it.
I liked the layout and structure of this chapter. The visual examples also help with the topic. Although the process may appear common-sense, it really helps beginners as a starting point or those who struggle with a straight-forward process. Like all plans and schedules, however, if you involve more than one person, you need to evaluate the flexibility of that schedule so that it does not become useless. I can imagine that most procedures are a product of collaborative efforts, especially in larger companies.
As many have mentioned, I found the information regarding steps to be the most helpful. What a difficult task to write a procedure that can accommodate both the novice user and the advanced user. To that end, I wonder which procedural format works the best when you have users with different levels of ability. I think maybe the standard format because information is written in step-by-step format, users can "enter" the procedure at the point at which they need assistance.
As our team begins to develop our testing guidelines for the Usability Assignment, I think this chapter will help us develop a list of criteria to use.
As I read this chapter, specifically the part about accommodating novice and advanced users, my mind went back to Gretchen's rhetoric class and the problem of defining the rhetorical audience. The problem is that "the audience" doesn't really exist as a single entity. Rhetorically, there are different ways of approaching the idea of the audience, but, ultimately, rhetors will have to play the guessing game sooner or later. You can analyze your idealized potential audience and usability test with a subset of that potential audience, but, in the end, you don't ever know if you've addressed your audience appropriately until your product gets out into the world and is used (or not used).
I suspect that, secretly, many technical communicators simply conjure up a mental image of a "novice" or an "advanced user" and try to imagine how those simulacra would interact with the program and what their expectations of the documentation would be. After all, how many technical communicators are given extensive budgets to usability test with their real audiences? And, if you are given a small usability testing budget, what confidence can you have that the few people you tested are representative of your intended audience? With small, subject specific products, you may have high confidence, but with larger products that intend to appeal across economic, social, and generational divides, can you have any confidence at all?
Nice job on this summary, group!
I agree with what the majority of the class said - I think the steps are really beneficial and easy to understand when listing procedures. I also thought of Mary's point, as well... wondering about the observation steps listed as more of an outline form.
This chapter really reminded me of all we need to think about before actually beginning the writing process. Thanks for the great summary!
Thanks for the great summary. I agree with much of the class; this chapter does a great job of providing a general overview while providing useful details, such as the tips about screen shots and the breakdown of the different help formats.
Good procedures writing is the "cash cow" for a lot of technical writers. And in spite of this book's editing errors the author does a good job of breaking down the elements of procedures' writing. I like how he instructs us on the advantages and disadvantages of using screen shots, cautions and warnings, notes and tips, and tables.
I also like how Barker did the same for choosing the appropriate procedural format.
Post a Comment