Barker, Chapter 2: Writing to Teach — Tutorials

Tutorials are designed to teach how to use something, such as new software. It may teach a beginner focused lessons on starting out, or it may teach an advanced user more complex focused lessons. Tutorials, like other software documentation, should be created with the user in mind.

Guidelines

There are seven recommended guidelines to follow for tutorial design:

1. Identify User Actions You Need to Support

Analyze the users of the program and their needs, including what they use on the job, what software features are essential, and what features are used frequently. Embedded tutorials are useful to detect important skill lessons, but it should be clear how to close the embedded tutorial if not needed.

2. State Objectives as Real-World Performance

The objectives of the tutorial should be stated in the module in terms of the user's performance. State exactly what will be learned in measurable terms.

3. Choose the Right Type of Tutorial

Types of tutorials include The Guided Tour, The Demonstration, The Quick Start, The Guided Exploration, and The Instruction Manual. The Guided Tour consists of an overview of the main features of a program. It can be online or in print. The Demonstration demonstrates specific actions in a program. Experienced users may use The Quick Start to jump right in to a program and start working with it. The Guided Exploration allows the user to determine the direction of the tutorial, exploring its options. Finally, The Instruction Manual teaches users step by step how to use a program, from basic features to more advanced ones.

4. Present Skills in a Logical, Cumulative Structure

It is not enough to prepare logical and organized lessons in your tutorials--you must also order those lessons in a logical and coherent way. Like other aspects of documentation, the proper order and structure will be determined through an evaluation of your user's needs, i.e., a typical-use scenario. Usually, the tutorial will progress from the general to the specific, the structure of which will mirror the typical user's workplace routine.

5. Offer Highly Specific Instructions

Instructions should emphasize scenarios that are familiar and applicable to the user. These scenarios should contain specific instructions to ground the user in the lesson. Keeping them grounded will help them fight feelings of insecurity they may be having toward having to master a new tool. Some examples of specific instructions include using concrete data, interface tools, screens, and specific commands. In addition, remove all distractions from the lesson, including page design elements that may interfere with the learning process.

6. Give Practice and Feedback at Each Skill Level

Giving users positive feedback in a conversational and positive manner will help orient them emotionally to the tool you are helping them learn and to the tutorial itself. Avoiding jargon and making liberal use of "you" and "we" will give the tutorial a "human touch."

Building consistent patterns gives predictability to the tutorial and reduces the amount of work the user must go through to understand the concepts that are being taught. Avoid alternative explanations because they may overwhelm some users and distract them from what they are learning. If feasible, build in practice exercises or quizzes into the tutorial to help keep the interest of adults who enjoy challenges and self-exploration.

Because most of your users will have competing demands on their time, keep the lessons short, about 10 to 12 minutes each. Also, let them know how to save their progress in case they need to shut the tutorial down and pick up where they left off at a later time.

7. Test Your Tutorial

Usability testing gives you necessary information about the effectiveness of your tutorial. If possible, test the tutorial in a real user environment. Focus the testing on the design elements, such as the cuing system and graphics. Perhaps most important, ensure that users can complete the lessons in the allotted time and that the lessons result in real learning.

Designing Tutorials

Because tutorials are designed to teach, the tone of the writer's persona must match the intended user to create a close relationship between the two. Because the goal of tutorials is to internalize work-related tasks and concepts, try to limit the scope of what the user is exposed to. This contrasts with other forms of documentation in which the writer attempts to be as expansive as possible. In order to narrow the scope of the tutorial appropriately, you must fully understand the needs of the user--which tasks are essential to them and which aren't? Without a thorough user analysis, it is impossible to narrow the scope of the tutorial appropriately.

Tutorial Users Need Special Care

Most of your users will be adults who have their own motivations for wanting to learn the tool that your tutorial is helping them master. For your tutorial to help them successfully, you must take into account the varied learning styles of your target population. As a tutorial designer, you need to understand how to limit the lesson times, prevent the user from being publicly humiliated for mistakes they make, give positive feedback, and make the user feel that they are self-directing their own learning.

Two Trends in Tutorial Design: Elaborative and Minimalist

The elaborative approach to tutorial design emphasizes reiteration to "bring the message home" to the user. Summaries, examples, and explanations all reiterate the learned material and may help the user retain and apply the knowledge they have gained. This approach is especially important for novice users with little-to-no experience with computers or the program being taught.The minimalist approach gives a nod to real human behavior: people often want to get off and running, without spending a lot of time in advance preparation. In the minimalist approach, the introductions and summaries are discarded because most readers will skip them anyway. To create effective minimalist documentation, use an action-oriented approach that is grounded in a workplace context that helps users recover from errors made and supports reading to "do, study, and locate."

Team 4 (Chapman and Lukkonen)

Campbell, Chapter 2: Where Do I Start?

In policies and procedures writing, we talk about the development process instead of the planning process. It’s important to develop the project instead of diving into writing, because if we immediately start writing, we may be missing something crucial to the project.

The four steps of development are

1. Planning
2. Analysis
3. Research
4. Prewriting

Each step should be covered, if even briefly, and all should be done in order. Outlining is not recommended because it wastes time and could cause errors.

Step 1: Planning

• A plan, in most cases, should be written
• This step is not always formal

Since every project has a deadline, a plan should be kept somewhat simple. For this, it is a good idea to plan the basics:

• Tasks
• Sequence
• Deadlines

Set a schedule

• List the steps
• Indicate team member responsibilities
• Make timetable estimates

A team’s size is important because too much work for few writers will make it difficult for the team to meet the deadline. Our text states the following when working with a team of writers:

• Select members with appropriate backgrounds or expertise
• Meet or talk regularly
• Establish ground rules
• Agree on assignments and responsibilities
• Establish a monitoring system
• Agree on deadlines
• Develop a team style guide

Be realistic: Make sure the plan is doable, and always check for conflicts and other possible concerns (such as other projects that have their own deadlines). A written plan should help address these possible road blocks.

Step 2: Analysis

In this step, the team should look at the project’s

• audience
• assignment
• context
• relevant research
• conditions for the work

Some concerns can be answered in analysis through the following:

• Look at who requested the project, and why the requested it. What led to the project’s conception? To what degree is the nature of the project? Is it technical or non-technical? Simple or complex?
• Know your goals. What do you want to result from the project? If you’re ever unsure, ask for more information (from knowledgeable sources such as the requestor).
• Know your audience so you can mold the document for them. What are their experience levels, interests, preferences, attitudes, and so on? How will they use the document?
• Know the project’s subject matter and its urgency. How big of an impact will it have on the organization? What are the conditions you will be working under?
• Go over important concerns with the requestor of the project. In this manner, update them regularly.

Step 3: Research

• First action here should be on matters of content.
• The amount of research here should be determined on what was found relevant in step 2.
• Ultimately, you will determine the amount of research.

Start with the most difficult research first as it will probably take the most time. This will give you time to ask questions and get clarification.

If it is possible, get information from experts who know the information you’re searching for. Also, talk with anyone who could provide input (such as the users of your document).

Relevant material should be read (books, articles, organizational files, etc.). And, of course, concentrate on critical information over anything else.

Step 4: Prewriting

Prewriting involves organizing the material, and this helps to speed drafting. This step is done before writing, and it is recommended to hold off writing at this point. An important question here is, “How do I convey this information to the reader in the clearest, most logical way possible?”

Content is key, so make sure all necessary information is gathered. The book suggests to practice mind-mapping (see example 2-8, p. 55) to gather and organize data. Mind-mapping reverses the process of outlining and allows you to focus on content issues first:

• It removes our creative side and brings all content to the forefront of organization.
• It helps you record your thoughts and knowledge at random.
• It is less likely that important information will be omitted.
• It may be easy to do, but it gets results.

Finally, in prewriting, you should develop a flow or sequence of the material that would be most logical to the reader. Will the reader use the information in a way that works for them and the organization?

Thank you, everyone, for participating in discussion on this chapter!

Team 3 (Lori Hood and J.J. Carlson)

Campbell, Chapter 1: What's a Policy, What's a Procedure?

What’s a Policy, What’s a Procedure?

You need policies and procedures because otherwise there would be chaos and frustration. Policies and procedures are the way an organization operates. Policies deal with the “what” and “why” while procedures deal with the “how.”

Policies are guidelines that regulate organizational action. Policies are used to explain an organization’s view on a certain subject or issue and why their view is what it is. Policies are up to each organization to decipher and regulate as long as their choices do not break any laws. Decision-making is the key in policy making, because if the organization doesn’t know what direction it wants to go in, the employees lose sight of what is important to the company and this can result in lost productivity and job loss due to the lack of clear direction.

Policies can be either ambiguous or specific, depending on the subject matter. It is up to the policy writer to determine when it is appropriate to be ambiguous and when more specificity is needed for certain policies.

Procedures are the normal method of handling things. Procedures tell employees how to go about their daily job in an appropriate and safe manner. Procedures are action oriented and can point out the consequences of not following procedures correctly. Procedures should be very specific, and oftentimes can be regulated by safety organizations such as OSHA, and will help employees to stay safe and in good standing while on the job.

Policies and procedures can be difficult to write because they require both an air of subjectivity and an assumption that the employee will take their own actions and position within the organization seriously and with regard to others on the job.

Policies and procedures should be carefully considered before they become “law.” They are not always appropriate, and they can sometimes lead to employees feeling micromanaged or result in more incidents because employees got “bored” reading through all the procedures and therefore didn’t. Be sure that the organization goals are clearly communicated, and employees will generally try to fit within those goals.

Written vs. Unwritten

Unwritten rules can sometimes be more preferred than written rules. We all have unwritten rules, whether we realize them or not, that come into our daily lives and work lives all the time. It is best to leave a policy or procedure unwritten when:

· It involves organizational culture and norms,

· It cannot be consistently enforced,

· It is potentially offensive or intrusive, or

· It simplifies another rule that employees already understand.

Sometimes, these unwritten rules DO need to be written down, but unless something serious has happened such as an accident or a complete disregard for even the ambiguity of the unwritten rule, unwritten rules are normal and almost expected in organizations.

What to Include in Policies and Procedures

It can be very hard to know what needs to be included in policies and procedures, especially when there are the aspects of keeping the rules ambiguous at certain times and specific at other times, or when there can be rules that do need to be written and those that do not. The audience is the key in determining what needs to be in your policy or procedure. Purpose is another big determiner in what is written. Writers need to determine what readers need to know as opposed to what they want to know. It is important to ask who wants readers to know specific policies or procedures, and if the writer can answer that question, it can be assumed that the policy or procedure NEEDS to be included. If information is interesting, but maybe not necessary, to the employee, that is information that they will WANT to know. Writers need to keep in mind that the readers of policies and procedures want to know what’s in it for them (WIIFT) – what it will mean to them and for them.

Discretion is key in determining the detail content of the policy or procedure. If a subject or topic is complex, or if the policy or procedure contains a legal aspect, the policy should be as detailed as possible to avoid questions or misinterpretations of the rule. Writers should be sure to do a thorough audience analysis before writing or updating policies because that is who the policies and procedures are directed at, and can help the writer to determine what level of detail is appropriate.

Manual or Handbook?

Once an organization has its policies and procedures written down, it is important to organize them into one place where employees will know where to go to find the information when they need to reference it. Many institutions call these organized books of information either manuals or handbooks. There are legal connotations associated with both of these terms:

· Manuals imply restricted circulation within an organization, and

· Handbooks imply general distribution.

If a writer is concerned at any point about a contractual issue, it is important to know the differences between the two as they could create legal troubles later.

Summary by Team 1: Amy Beeman and Jane Xiong

Barker, Chapter 1: "Understanding Task Orientation"

Introduction. This chapter helps writers achieve two goals: encourage users to learn the program and to apply the program to the workplace. The chapter also defines task orientation, the nine characteristics of manuals, the five characteristics of the default user manual, and the five characteristics of the task-orientated user manual.

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.

CHAPTER OVERVIEW

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:

1. Emphasize Problem Solving: help users solve problems in the workplace.
2. Provide Task-Oriented Organization: organize our manuals in such a way that it will match the tasks that the user will need it for.
3. Encourage User Control of Information: write the manual in such a way that the user decides what the software program will do for them.
4. 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).
5. 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).
6. Design for Users: the organization reflects the user's needs.
7. 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).
8. Encourage User Communities: task-orientated documentation encourages users to identify and get help from users, usually those in their user group.
9. 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:

1. 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.
2. 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.
3. 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

Welcome to our course blog

We will use this blog to discuss our course readings for the semester. Welcome!