But before we begin, what is task-orientated documentation? Task-orientated documentation is really the challenge of creating documentation that looks at the process of writing and finds ways to learn about users. Task-orientated documentation consists of manuals and help that reflect real users and human forms. The process of task-orientated documentation requires that you analyze the user in his or her work environment to discover the rich texture of activities within the software program and where the manual fits. Barker's goal is for us to write task-orientated documentation with the manual's user in mind. This book has the technical communicators goal in mind--to be an advocate for our readers!
Barker talks of “actions” and “operations” when explaining the computer user’s environment. “Actions are tasks that grow out of work situations that often require communication and thought.” In other words, actions have a goal and purpose, such as producing an easy-to-read annual report. On the other hand, operation-centric documentation teaches one narrowly focused commands, such as the menu functions on a program. (e.g. “save to disk,” “spell check,” etc.) The thorough exploration of both, actions and operations is essential to task-oriented documentation.
GUIDELINES All software documentation should explain and show connections between the user's work and the computer program. Barker's book will explore different techniques that will help us write a manual.
Here are some of the techniques we will learn more about in coming chapters:
- Emphasize Problem Solving: help users solve problems in the workplace.
- Provide Task-Oriented Organization: organize our manuals in such a way that it will match the tasks that the user will need it for.
- Encourage User Control of Information: write the manual in such a way that the user decides what the software program will do for them.
- Orient Pages Semantically: this is a design that arranges the elements of the page meaningfully, according to the elements of the functions the user needs to perform (i.e. putting important elements first).
- Facilitate Both Routine and Complex Tasks: the documentation should include repeatable tasks (routine tasks) and tasks that require the user to apply knowledge that isn't easily codified in step-by-step procedures (complex tasks).
- Design for Users: the organization reflects the user's needs.
- Facilitate Communication Tasks: the manual requires users of the software to communicate about their work (this means the documentation depends more on the workplace demands of the user than just on the software features).
- Encourage User Communities: task-orientated documentation encourages users to identify and get help from users, usually those in their user group.
- Support Cognitive Processing: the documentation uses principles of knowledge representation, parallelism and analogy to convey software features and applications to workplace tasks.
DISCUSSION Principles of software documentation. Barker's book addresses a need for the business and the professional workplace to use software efficiently and effectively. The software user has two goals: the goal of learning a program and applying the program. We have to convey the correct instructions on learning to use the program, helping users navigate menus, learn commands, and terminology of a program. Therefore, our goals as technical communicators are to teach the features of the program and tell how to apply the program to complex tasks.
A definition of task orientation. Barker defines task orientation as: a design strategy for software documentation that attempts to increase user knowledge of and application of a program by integrating the software with the user's work environment. Our manual should increase job efficiency, not hinder it.
Theory behind task orientation. There are two ways to define the user of any software, as a person who needs to learn about menu functions and commands, and as a person who uses the software for workplace ends (this is our main goal). Barker categorizes these two users as the default user and the task-orientated user. Let's explore these with more depth... (just as a note, Barker explains each bullet point in his first chapter.
Default user:
- Perceives job skills as decreasing in importance
- sees computer use as separate from job goals
- becomes isolated from other employees
- fears remote supervision
- suffers from information overload
Task-oriented user:
- challenged by redefined work activities
- conceptually orientated
- aware of user communities
- self-managing
- supplied with resources
We want to shape our software documentation and aim it towards the task-oriented user. We want our documentation, therefore, to be task-oriented. :)
The forms of software documentation. There are different types of documentation users. Users use manuals for different tasks, including: planning tasks, decision-making tasks, problem-solving tasks, operating tasks, and knowledge tasks (please see Table 1.6 on page 19 for more information). When we create our manuals we need to look at how people are using the software and how they are applying the program to their work. Users first often learn how to apply the program to their work, how the features match their workplace goals, and how the actions they perform correlate to the menus and the screens. Next they use the program on a daily basis and sometimes more, and then finally users become advanced so that they just need to look up information about a program or troubleshoot error messages.
Three manuals can be created for each type of user:
- Tutorial documentation: intends to teach the basic functions and features of a program to a person can begin applying the program to workplace tasks. Examples: getting started guides and online tutorials.
- Procedural documentation: intends to guide the user in everyday use of the program, often when the users need information at the time of user. Example: step-by-step procedures.
- Reference documentation: intends to supply information "about" the program to advanced users that rarely consult the user's guide or tutorial but occasionally need to look up information about the program. Example: alphabetical listings of program features, lists of examples, file formats.
The processes of software documentation. It really begins by exploring what users are using the software for; again, taking that human approach. This is a process of exploring user needs and then of constant involvement of the user in the process of writing and testing (this process is called usability process). Users and their needs drive the writing. Please see Figure 1.8 for the different stages of writing software documentation, which include the planning, development, and evaluation stages.
Finally, Barker concludes “A manual that integrates a software program into the user’s environment has a better chance of getting used than a manual that only documents the features of the program.” Words of wisdom for all of us.
Thank you for reading our chapter summary!
Jennifer and Gary
11 comments:
I really appreciate the style consistencies within this book. It is laid out in a way that makes it very easy for me to follow. Since I am brand new to software documentation, I think this will really help with my learning throughout the semester. The examples and images reinforce the information in the book and enhance my understanding of the content.
I am wondering if anyone else, after reading this chapter, felt like it could have been titled "The Psychology of Documentation?"
We, at technical communicators, have the daunting task of "making the thing work." It seems to me that the ultimate success or failure of a software product lies in the ability to make the user comfortable with it. I appreciate Barker's insistence on orienting the writer to the situation. We've heard over and over that we are advocates for the end user and Barker brings this point home in Chapter One.
I guess it really comes down to putting yourself in the user's shoes. We must see the pitfalls, quirks, and nuances of the software and help the user (no matter what their comfort level and product knowledge is) to make the software useful and productive for them.
We're charged with a lot of responsibility as technical communicators. I guess that's why it's an exciting field to be in.
Thanks for an intersting summary of the chapter. The three functions of help needed was right on for how I use computer documentation. The first step - I always want to get started right away. Give me a quick tutorial so that I can jump right in. Then, as I get going, I want to be able to look things up that I can't quite figure out. Eventually, the manual comes out only occasionally when I am trying to do something new and I can't get it to work. I do think it is interesting that we are talkiing about manuals when, in reality, there are very few manuals around. The help features are almost always a part of the program. As long as you can figure out the right word to search for, you can find what you need. If you don't know the correct terminology, yikes. It is then that you kind of miss being able to flip through an actual book.
Since I am a very structured person, I really appreciated your summary. I do agree with Lance a bit: mostly due to the fact that the author provides definitions of processes and lists of required tasks.
The chapter helped me to verbalize some things that we as technical writers do: some of the tasks often go unnoticed or unappreciated. We are more than writers or even communicators: we are facilitators and planners, designers and often even sales people, trying to pursue the team of the benefits of a certain process or the need of a document.
I agree with Lance, this reads almost like a psychological study. The audience is emphasized in much of technical writing, but I don't recall any text actually breaking down categories of user and suggesting different strategies for different users quite like this. When I think of manuals, I tend to think of a single type of user, a novice who is likely being forced to read what they expect to be dry instructions. Despite studying TC, I often feel this way about manuals. It's refreshing to have some direction in thinking more critically about documenting processes.
This chapter has me thinking a lot about the interplay between documentation and the software product itself. We, as technical communicators, privelege the role of documentation in helping the user understand the program--without excellent documentation, no product can survive, right?
Well, what about Google? They are a multi-billion-dollar corporation and the bulk of their fortune derives from software that they essentially do not support. They produce no manuals, and they do not allow users to contact the company directly. They do offer some basic tutorials for some of their products (such as Gmail), but the documentation they provide is far from comprehensive. What they have going for them is that their software is so intuitive and easy to use that they do not have a strong need for extensive documentation. Where does that leave the documentation writers?
Unrelatedly, I agree with Keeley about the trouble with online documentation: if you're a newbie then you often don't know the terminology to be able to search for answers. This is a problem I have faced time and again, and it can be very frustrating. If online documentation is produced, there often needs to be more than a reference guide available. But even if an online user's guide exists, they often aren't as user-friendly as print versions.
This chapter made me think back on the work we've done in my department over the last 18 months. In order to design a new electronic medical record system, we first met with users to learn about their workflows. We talked about what was possible in the new system and then configured it according to their wishes. Once it met with their approval, we invited them to participate in usability testing, with test scripts that each reflected a patient's stay at the hospital from start to finish.
And in addition to teaching the users the basic "how-to's", the instructors used scenarios to demonstrate how the knowledge could be applied.
Now that I've had this experience, I have to say that I believe Barker is correct in his approach. It's much more useful to relate information to someone's needs than to just identify the components.
...now if we can just figure out how to create a culture where people will want to consult a manual. In this age of "quick fixes," even the easiest-to-use manual will often be overlooked. I'm not sure if that is because the perception of manuals is that they are difficult to use or if people are not investigative enough (dare I say lazy??) to try to solve their own problems/questions.
For instance, I've used Microsoft products in an educational setting for years. Early versions were difficult to use, and like Keely said, if you didn't know exactly what you were looking for, the Help feature wasn't very helpful. Now, I really do believe Microsoft has vastly improved the Help feature, but 9 times out of 10, students will still either ask me or their neighbor or keep trying something different rather than use the Help feature.
In the situation I’ve described, I’m not sure where it really fits with Barker’s discussion about default- vs. task-oriented users, but maybe developing a person’s willingness to troubleshoot will ultimately produce more task-oriented users.
Thanks for the great summary, Jennifer and Gary! It was very helpful reading it after I read the chapter in the book because it was a good review of the major points Barker made. I also thought the illustrations he chose to include were very helpful because they supported the point he was making and were good examples of the ideas and processes he discussed. I thought this was a good introduction to the topic; the arrangement was also easy to follow, and the key items emphasized in boxes helps to draw the eye to them.
Thank you for summary of Chapter 1 by Barker.
As to the comments, I do agree with Keeley and Lori about use of manuals. Presently, I have just started to learn to work with a specific software program. In order to learn how to use/apply one of the features I am not very familiar with I have refrained from consulting the manual even thou there is one available to me. I have been delaying this for several day and am contemplating to try to figure this on my own or worst comes to worst Iam thinking about talking to someone who knows this program. Go figure, even thou I consider myself task-oriented user..
There is tendency in educational settings to refer to the help features last. I do see that with my students when they work with eFolio, creating their own websites. They are more likely to ask me or someone else just like Lori said before they resort to manual or help tips.
Lance, I would agree that this chapter tends to asks us to play the Psychologist, but we all agree that this is the only way anything can be improved upon. If we write for ourselves an no one else, we will not succeed in making our document usable.
Another way to look at it is writing for another language. If we don't know the language, we are not going to know where to start. If a technical communicator wants to write a manual for the engineers in the company, he or she needs to first become familiarized with the tasks and equipment the engineers are involved with.
I would say that this chapter was well organized, and Barker does a good job of getting the appropriate concepts across. It's also a great chapter to start with, because audience analysis is key.
Post a Comment