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)