Ahles/Hennis-Barker Chapter 3
Chapter Layout
Barker writes about procedures in chapter three. The procedures he refers to are called guidance, how-to, and step-by-step. He presents different methods for writing different types of procedural instructions and suggests that learners want to know both how and why the software works.
What is a Procedure?
Barker says there are three types of documentation: guidance level, teaching level, and support level. Teaching level documentation is also called tutorial; the object is to teach the user the program and its uses. Support level (or reference) is user-defined; the user determines where they find the information and how much of that information they will use. Guidance level documentation falls somewhere in between teaching and reference; the user may be familiar with the program and only needs a reminder of what to do.
Guidelines for Procedures
According to Barker, authors need to make the procedures useful by tailoring them to activities that normally occur in the workplace. The procedure will be much more meaningful to the learner if it relates to something he/she does in the workplace every day. The procedure should be recognized as a building block that fits into the larger picture of what the office accomplishes in a normal day.
The writer needs to determine what the end-user will need to accomplish their task. He does this by doing a user analysis (to be covered later). The user analysis will determine how much or how little information will be included in the procedure. Barker (p.68) says that the writer will use a combination of tools in the procedure including:
- Screen Shots
- Cautions and Warnings
- Tips for Efficient Use
- Tables w/ Option for the User
- References to Other Resources
- Explanations
Formats
Barker suggests that there are basically four formats to use when writing procedures. He calls them the standard format, prose format, parallel format, and embedded help. All procedures, regardless of type, need to have evaluations done on them to makes certain that they are reasonably complete and accurate.
The standard format contains the steps in a numbered sequence from first to last. This type of procedure is often seen in instruction manuals such as software books. Most of us have seen it before, and Barker suggests that user recognition makes this type of procedure useful.
The prose format puts the procedure into sentences and paragraphs instead of numbered steps. This type of procedure is used for simple tasks done on a simple interface.
Parallel format is used with complicated fields or boxes. Numbered (lettered) steps are used along with prose explanations.
Embedded help is used when the user needs help that is specific to his location within a program. Embedded help uses markers within the program which, when called upon, present the user with information that is relevant to their place in the program. Embedded help uses various methods for presenting information including tips, cues, demonstrations, and trouble-shooting.
posted by Larry Hennis | 5:23 PM
9 Comments:
Larry, your comments are very descriptive of the process a technical writer engages in while writing procedures. In the real world I have found that many times the technical writer is handed a procedural document that has been written by an engineer and asked to "clean it up". The engineer does not understand what we do. They just know if they like the end result or not. Many times I feel more like a technical editor instead of a writer. It can sometimes be a challenge to edit an engineer's document, fulfilling our need to "clean up" the prose - and simultaneously not change the meaning being conveyed. This, I have found, is almost impossible to do unless the technical writer has engineering skills. Techncial writers are the bridge between engineering and the audience. As such, we need skills in both engineering and technical communication. I have found that it is the combination of skills that makes me employable - not just the technical communication knowledge.
Wes and Larry did a good job of writing a synopsis of this chapter...presented in a very readable format.
I read Carl's comment about being asked to "clean it up" with amusement or maybe it's bemusement. Along with "clean it up," I get instructions to "pretty it up."
I too feel more like an editor than anything else right now. My authors know insurance, and their level of knowledge is usually far greater than the average processor who reads their documentation. I sometimes feel as if I need to be an advocate for the end users.
We have provided a template and some training for our authors, so we're getting on the same "page" for consistency's sake. I wonder if it would be helpful if my department presents Barker's 3 types of documentation to the authors and come to an agreement on the type of writing the authors are doing for specific situations, instead of using only one template.
First of all, nice job on your post. The one thing that I notice as I read Barker is that everything that seemed so simple, i.e. writing instructions, is actually a very complicated and thoughtful process. I can't even think of one time that I read an instructional document and thought about these different levels that Barker talks about. I always thought an instruction booklet was just somebody who knew how to do it telling the audience in most simplified terms on how to achieve the desired end result.
A very nice over view on the formatting of procedures. The description for parallel was nicely done, as it was hard to understand in the book without the visual aid. I am beginning to wonder other kind of thought goes into the construction of a manual; do they often need a guinea pig to run through the instructions for them to make sure that they are clear enough?
This was a great summary of Barker's text. For some reason, I have a better understanding of the barker text than the other two we use for our class. I think Barker gives good explanations and descriptions of everything that goes into creating documentation -it also helps to have so many examples and visuals. Users don't always realize all the work & thought goes into writing instructions, but it is very important for writers to consider all aspects of the documentation including which type, format, and visuals to use.
I noticed in Anne's post that she said she feels like she is forced to be the user advocate. I've heard about this several times in classes of mine. In many ways, that is the goal of a technical writer or editor: to be the voice and representative of the end user. This means not only writing a document that helps them to understand a program the best way possible, but also to be in contact with the programmers as early as possible and get them to write the program with the user in mind. Isn't that the goal of any ethical business professional; to make the best product they can?
One further comment I'd like to make about Barker is his prevelant use of screen shots. I think that, no matter what type of computer program you are writing for, a screen shot will help guide the user faster than just telling them what to do. I think all Creative Writing courses really promote the idea of show, don't tell, and I think it's a concept worth translating over to technical writing, too.
I have used all of the types of documentation the Barker discusses in the text. i think embedded is probably the most used beduase people don't have to waste time reading stuff they don't need. No one opens the book unless they have to, this way they only get help if they want it and then immediately. I have written procedures for a couple classes and I prefer writing the step by step format because it is so clean cut. I also like to use them becuase it is a very direct path and you know if the help you need is in the book or not.
Keep up the good summaries of the chapters. I might be able to sell my books for some money before the end of the school year.
As Carl said with his comments sometimes he is more of a clean up man than a producer. I think this chapter has to been taken in two different views, one from that of a producer that is working with the engineers and two that of writer that is placed more in the area of just an editor. Depending how you are involved can really make a difference as to the outcome of the document.
Post a Comment
<< Home