Guidelines for Developing Instructions: Chapter 4 (Case/Pass)
Chapter four of Guidelines for Developing Instructions develops a series of rules for task preparation. The authors argue that once the user begins a task, the user should be able to continue to completion without having to stop to find tools, buy supplies, prepare equipment, or readjust materials. Therefore, it is essential to provide the user with a planning information page to explain what a user will need to have or need to do in order to successfully complete the given task. Below are the thirteen rules of task preparation as discussed in the book, many of them directly quoted:
Rule 1. Include planning information at the beginning of the procedure when the task requires any of the following:
- Tools, equipment, or supplies
- Preconditions to be met before the work can begin
- consideration of a variety of equipment configurations
- Different numbers and types of workers
- A number of tasks grouped into different series
When deciding how much planning information to include, consider the expected mode of use, and what the expected user will know, not know, or need to know. Be as specific as possible.
Rule 2. The format for planning information should abide by all of the following:
- it should be consistent throughout the entire document
- it should enable quick and accurate scanning
- it should follow the normal document presentation principles discussed in chapter three.
Rule 3. Use separate instructions for each model unless they are identical or almost identical. This includes multilingual instructions; a set of instructions should include no more than two languages to prevent the user from being lost in unusable information.
Rule 4. When the instructions apply to only specific models of a product, list the models under the heading. The same rule applies to when a step or a task only applies to specific models of a product.
Rule 5. When the instructions apply only to specific equipment items of a product, list the equipment under the heading. This rule also applies to when a step or task only applies to specific equipment items.
Rule 6. Include in the planning information the conditions or requirements that must be met before starting the procedure. Warn the user beforehand (assuming the user will read the instructions first) of whatever needs to be done before trying to do the task.
Rule 7. When there are multiple prerequisite conditions, present the conditions in list form. This will help the user take a step-by-step approach to completing the prerequisites, and will increase the odds that the user won’t miss a prerequisite.
Rule 8. Use ANSI Z535.4-1991 or -1998 Product Safety Signs and Labels as a standard for presenting safety information. These are standards regarding the efficient usage and visual appearance of the words Danger, Warning, and Caution in documentation.
- Danger indicates an imminently hazardous situation that, if not avoided, could result in serious injury or death. Danger should appear in white letters on a red background.
- Warning indicates a potentially hazardous situation that, if not avoided, could result in serious injury or death. Warnings should appear in black letters on an orange background.
- Caution indicates a potentially hazardous situation that, if not avoided, could result in minor or moderate injury. Cautions should appear in black letters on a yellow background.
Rule 9. When safety is a concern, explain the hazardous conditions to the user ahead of time in the planning page. Tell the user what to watch out for, and how to know if they have done something potentially dangerous.
Rule 10. Identify any help required of another person to successfully complete the task. If the user will need other people to be involved in the task, the user should know about it ahead of time so he/she can arrange to get the help.
Rule 11. Identify the resources and materials needed to complete the task. When writing for a technician, you do not need to include things that are always present in the technician’s workspace, such as a set of standard tools. However, when writing instructions for consumers, you should list all tools, expendable resources (gas, grease, tape, etc), or products needed.
Rule 12. When a sequence of tasks is involved, list the items and resources needed by task so the user knows which items are for which task. That way, if the user is only going to complete one task, he/she can prepare just for that one task.
Rule 13. When the package or procedure includes more than one task, provide a table of contents as part of the planning information to help the user quickly find the task of interest.
posted by William | 10:02 PM
9 Comments:
I found the section on safety signs particularly interesting in this chapter. I had never considered or wondered about the difference between the "warning", "caution", and "danger" terms and always kind of thought they meant the same thing. But in reality, they are all very different terms, and this is important to realize in writing documentation, and is also important to know as a reader. You don't want to misunderstand a safety sign in a hazardous situation - it could lead to deadly results!
It is typical on large projects to find that a professional project manager is assigned to direct your planning activities. As such, a project timeline will be created and technical writing tasks will be incorporated into the project plan.
In my experience project managers typically lack the knowledge to delve deeply into the planning process for technical documentation. They tend to only possess a big picture level of understanding of the processes and procedures utilized by technical communicators. However, their lack of detailed knowledge doesn't prevent them from managing the project. SMEs are expected to manage details below the task definition level.
It is common to find the project plan documented using MS Projects. There are other tools available but MS Projects seems to be the most common tool.
Again I appreciate the thorough review on this chapter since I don't have the textbook. Appears to be a lot of good information.
I do agree with Carl's comments about project managers. Their job is to push a project to conclusion, but in my experience, it can be frustrating taking time to explain to them why we need the software we do, why it takes a longer period of time to get processes written well, etc. They want to get to the deadline and need to be instructed along the way about the actual steps it takes to accomplish the goal.
I agree with what Emma said about the differences between safety signs; I had never even thought about how different they really are before! Sure, I’ve noticed that some are red or yellow, but had never bothered to think of why that is. When I read that I was amazed. I guess it just goes to show you how you can never stop learning, even when it’s a subject that you probably should have thought about before.
Rule 11 took me a bit by surprise, stating that the writer should list all the tools needed to complete a process. Now, the text says that users should know how to use basic tools such as hammers, screwdrivers, etc. I knew a girl in high school who honestly thought that there were separate hammers for left-handed and right-handed people. So when I go on to read that including instructions on how to use the tools is optional, I can’t help but wonder how many people are like that girl and what I would write for them.
Rules, rules, rules--everything in life has too many rules. Oh well, I'm a reasonably structured person and rules make it easier to accomplish whatever it is you are trying to accomplish (if you follow them).
This set of rules contain a lot of common sense topics. There are certain rules that I particularly like-such as using one set of instuctions for only one model (that is, don't combine multiple models into one instruction guide). I have encountered sets of instructions that cover multiple models and I find them extremely confusing. I end up lookingfor parts or features that are not present on the model in my hand. Ugh!
I also find it interesting that instuctions for technical people and for consumers need to be written on different levels (remember that blurb about writing at the sixth grade level so people caould understand what you've written?) Yes, I also like tables of contents to locate the specifics of what I need (reference document).
In the job I do, I encounter caution, warning, and danger labels all the time, so it was nice to be reminded that not everyone knows the differences between the various labels.
Again, I'm just amazed at how much thought and planning goes in to writing a set of instructions. I guess I never thought that much about it until this class but still..I am surprised by how much time and energy is devoted to making a process for developing instructions to any given situation. I also enjoyed the part about the differences between signs and how important it is that we understand those differences otherwise the consequences could be deadly. Nice summary!
Considering the subtle differences between words of the same meaning is very difficult when only using pictures. Finding ways to convey these words through images is important so the reader doesn't get a different meaning.
This chapter covers what is one of my favorite topics in technical communication, standardization. Maintaining standardization is very important. As with this chapter’s discussion of the how Danger, Warning, and Caution signs should be produced as in shape and color.
I find it discomforting that this brief chapter pretty much summarizes a month of English 472. Like others, I always more or less assumed that Danger, Warning, and Caution were synonymous, with just slight variations to extremity. I can see though that depending on the situation, getting the "sternness" of a warning wrong may result in trouble for the company I'm working for.
Post a Comment
<< Home