Barker ch 2 Pass/Case
Chapter 2 of Writing Software Documentation covers an overview to writing tutorials for computer programs.
Barker begins by identifying seven guidelines essential to writing an effective tutorial:
Identify User Actions You Need to Support—in other words, analyze your user and what specific tasks they will be doing with the program. Tie the program’s features back to the user’s goals and how they can use the program to accomplish them.
State objectives as Real-World Performance—Be realistic. Start writing a tutorial by stating, in measurable terms, what tasks you want the user to be able to do after using the tutorial. Often it is beneficial to state these goals in the tutorial for the user to see.
Chose the Right Type of Tutorial—Analyze your user and decide what format of tutorial will suit their needs the best. 5 types of tutorials Barker discusses in the text are: The guided tour, the demonstration, the quick start, the guided exploration, and the instruction manual.
Present Skills in Logical, Cumulative Structure—Imagine the typical-use scenario for your user, and use it to build your tutorial structure. Order your tutorial steps, tasks, or modules based on how your user will most likely be using the program once they learn how to use it.
Offer Highly Specific Instructions—Be as specific as possible. Don’t give general or vague information (such as telling your user to ‘enter any name’) just because your users have different perspectives of various things. Guide the user to exactly where they need to go, and tell them exactly what will help them get there.
Give Practice and Feedback at Each Skill Level—Be positive and encouraging towards your user, and remind them of the benefits of learning how to use the program.
Test Your Tutorial—Be an advocate your user by making sure that the product they get will do what they want it to do.
The second half of this chapter is dedicated to the difference between elaborative and minimalist approaches when writing tutorials. These two perspectives on writing seem to be dichotomic, one valuing thoroughness and the other valuing brevity. Sometimes the minimalist approach will be a more useful approach for a project, and sometimes the elaborative approach will be more useful, so it is worth it to explore both perspectives.
The elaborative approach focuses on peoples’ ability to retain information more thoroughly through repetition. To achieve this repetition, the tutorial utilizes introductions, summaries, examples, skill tests and a variety of other ways to present information. This approach is better suited for users that are new to computer usage, complicated procedures, or for situations in which the user must learn abstract concepts.
In contrast, the minimalist approach plays off the belief that users do not want to read instructions or unnecessary information. To follow these beliefs they try to teach using specific tasks related to the use of the software while letting the student explore the program. This approach is better suited for users that are familiar with computers, programs that require creativity from the user, or programs that have intuitively-designed interfaces.
Barker begins by identifying seven guidelines essential to writing an effective tutorial:
Identify User Actions You Need to Support—in other words, analyze your user and what specific tasks they will be doing with the program. Tie the program’s features back to the user’s goals and how they can use the program to accomplish them.
State objectives as Real-World Performance—Be realistic. Start writing a tutorial by stating, in measurable terms, what tasks you want the user to be able to do after using the tutorial. Often it is beneficial to state these goals in the tutorial for the user to see.
Chose the Right Type of Tutorial—Analyze your user and decide what format of tutorial will suit their needs the best. 5 types of tutorials Barker discusses in the text are: The guided tour, the demonstration, the quick start, the guided exploration, and the instruction manual.
Present Skills in Logical, Cumulative Structure—Imagine the typical-use scenario for your user, and use it to build your tutorial structure. Order your tutorial steps, tasks, or modules based on how your user will most likely be using the program once they learn how to use it.
Offer Highly Specific Instructions—Be as specific as possible. Don’t give general or vague information (such as telling your user to ‘enter any name’) just because your users have different perspectives of various things. Guide the user to exactly where they need to go, and tell them exactly what will help them get there.
Give Practice and Feedback at Each Skill Level—Be positive and encouraging towards your user, and remind them of the benefits of learning how to use the program.
Test Your Tutorial—Be an advocate your user by making sure that the product they get will do what they want it to do.
The second half of this chapter is dedicated to the difference between elaborative and minimalist approaches when writing tutorials. These two perspectives on writing seem to be dichotomic, one valuing thoroughness and the other valuing brevity. Sometimes the minimalist approach will be a more useful approach for a project, and sometimes the elaborative approach will be more useful, so it is worth it to explore both perspectives.
The elaborative approach focuses on peoples’ ability to retain information more thoroughly through repetition. To achieve this repetition, the tutorial utilizes introductions, summaries, examples, skill tests and a variety of other ways to present information. This approach is better suited for users that are new to computer usage, complicated procedures, or for situations in which the user must learn abstract concepts.
In contrast, the minimalist approach plays off the belief that users do not want to read instructions or unnecessary information. To follow these beliefs they try to teach using specific tasks related to the use of the software while letting the student explore the program. This approach is better suited for users that are familiar with computers, programs that require creativity from the user, or programs that have intuitively-designed interfaces.
posted by Lindsay | 7:22 PM
9 Comments:
I've found that in an engineering environment, the majority of users take the minimalist approach. They are tinkerers and want to play with a program instead of read the manual. It becomes a matter of pride to engineers that they can learn a program without opening the manual. Ego and programming skill seem to go hand in hand.
So I guess the rule of knowing your audience is vital here. What kind of users are most likely to read the manual? Once we know the answer to that question we will also know what type of approach to take in writing the manual.
I don't know about computer programs but I know plenty of people, myself included that enjoy trying to figure something out without opening or using the manual. It's an ego thing. So like Carl said, it's vital to know your audience. Do you start at step 1 or start later on the process taking into account that your user probably won't open the manual until they get stuck at a certain point. However, I think when it comes to computer programs or any computer lingo, I prefer to start at step 1 and go from there.
"Manuals are to be used when you can't figure it out yourself." Unfortunately, there may be more truth to that than we'd like to believe.
I find it amusing that, even though I spend my workday helping authors document procedures for online manuals, when it's time to learn new software myself, I usually skim a quick start guide to make sure I don't screw up my computer, then plunge in. I'll refer to the written manual if I hit a roadblock.
My work audience is probably more captive than someone who purchases software on the shelf. We don’t produce many tutorials as such. Federated uses training sessions to introduce new procedures, using the new online documentation. Users must read the documentation to do their jobs, or suffer the consequences.
I think that each of tutorials that Barker discusses have their own strengths and their own merits. While some might like a guided tour, others just want to know the bare bonesof the quick start and get to work. Personally, I think it depends of the type of software. For example, if I'm working with an MS Office type of software, I would want to moneky around with it on my own. If it was some new software--a media editor or something--I would probably want a good introduction before I start on my own. It basically comes down to what I would be familiar with versus what is totally new to me.
I've used tutorials to learn new software and I've found them to be very useful. They show you how the program works in an actual-use setting, and you can refer back to them if you forget how something works.
Do I like to learn something on my own without opening the manual? Sure. But the practical side of me knows that I only have a limited amount of time to learn, and if you try to figure things out on your own you might never "get it."
I think you can get MUCH more of a learning experience from attending classes/seminars, but sometimes they aren't available or cost effective, so a tutorial is a reasonable substitute.
After reading this chapter, I find myself being a user under the minimalist approach type of tutorial. I guess I'm more familiar with computers, so I generally like to skip ahead and try things on my own. However, it is also nice to have detailed instructions too, because sometimes jumping ahead in learning software can lead to mistakes and problems.
I definitely agree with Barker that it is important to be as specific as possible when creating tutorials - I have had experiences with vague instructions that made me wonder if I was even doing the right task!
I myself have found that while I do prefer to just plunge in, this is often not the wisest move. There are many times i'll have spent weeks just toying around with a program, and then after reading a simple tutorial, will learn more in the thirty minutes than in the past month. I'm sure I'm not alone in this, so the only option I can assume to be true is to have both tutorials available, one that goes "Alright, go on and play," and another that says "This is how to really work with the program."
I personally love figuring things out for myself, it gives me s sense of acomplishment and makes me feel smart. If I need to i'll read the manual but I think I can do it myself over reading steo by step instructions.
With my experience of the tutorials that I have used with different software it seems that the tutorials are set up at the difficultness of how hard the soft ware is to use. The advanced the software the harder the tutorial is to learn and visa versa with easier software. I would like to see tutorials designed for different levels of users. There could be one for basic users and one for experienced users all with in the same tutorial. That way it give the user two different ways to learn the material.
Post a Comment
<< Home