Barker - Chapter 2 Summary

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 2 – Writing to Teach: Tutorials

This chapter focuses on the first of Barker’s three forms of software documentation: tutorials. Barker begins the chapter by explaining its objective, which is to offer “examples, guidelines, and discussion” for designing effective tutorials. He continues by describing tutorials as a form of documentation that involves focused lessons which guide a user through a process, assuming that their proficiency with the software will increase as they practice using it to complete tasks.

Barker divides the content of the chapter into two main sections, Guidelines and Discussion.

Guidelines

Barker presents a series of guidelines that are meant to provide a basic procedure by which one can create effective task-oriented tutorials.

Step 1 – Identify User Actions You Need to Support

Barker recommends performing a thorough user analysis to determine the actions and scenarios that would be most relevant to a particular use. Within an organization, it is possible that a single piece of software will be used in different ways by different employees. It is useful to identify and list program skills that a user will need to accomplish specific tasks. Some criteria that can help in selecting which program features to focus on include the degree to which those features are:

• Central to job performance
• Essential for efficient software use
• Performed frequently

Another way of approaching this challenge is through an embedded tutorial (or EPSS) that detects when a user may need help on a particular topic and presents itself automatically at that time.

Step 2 – State Objectives as Real-World Performance

Tutorial writers, Barker asserts, should carefully define the learning objectives that they would like their users to achieve, and then state them for the user at the start of the lesson. These should inform the user, in measurable terms, what they will be doing in the tutorial and what skills the activity will impart to them.

Step 3 – Choose the Right Type of Tutorial

Barker describes several loose categories of tutorials, which serve different purposes depending upon the situation. The Guided Tour is an overview of program features that informs and persuades the user as to the usefulness of the program in a low-interaction environment. The Demonstration is a more focused presentation of a particular program function being performed, which tends to be passively viewed by users. The Quick Start is a form of documentation that is generally aimed at more advanced users and provides the basic information that one needs to dive into the program and interact with it on their own. A Guided Exploration guides a user through a procedure, but allows for some experimentation on their own. The most traditional form of tutorial is the Instruction Manual, which attempts to teach as much of the software as possible through a full series of interactive lessons.

Step 4 – Present Skills in a Logical, Cumulative Structure

A key component to effective tutorials is arranging the various lessons in a logical structure. This is often accomplished by organizing the lessons procedurally in accordance with typical workplace scenarios. Common cumulative structures include such progressions as beginning to advanced, generalized to specialized, and using default options to using customized options.

Step 5 – Offer Highly Specific Instruction

By soliciting very specific actions and information from their users, tutorials promote real-world skill building as well as confidence and interest in the program. Some examples of specific instructions include:

• Specific data
• Tools
• Screens
• Commands

Step 6 – Give Practice and Feedback at Each Skill Level

Barker recommends maintaining a highly positive tone throughout the tutorial, and praising users for their accomplishments whenever possible. He also advises building a pattern of exposition, by which the tutorial writer continuously:

• Gives an action to take
• Explains the results

Keeping lessons short (under an hour and ideally 10-12 minutes) will help make the tutorial more accessible to busy users. Including a convenient means by which one can pause a tutorial and return to it later is also beneficial.

Step 7 – Test Your Tutorial

Like any documentation, tutorials should undergo a thorough usability test. There are a variety of methods for doing so, but the most revealing information often comes from observation of an actual user making use of it in a realistic scenario.

Discussion

In this section, Barker explores the different elements that make up tutorials, and two philosophies of teaching that can inform tutorial design decisions.

Designing to Teach

Here, Barker offers some advice on how to decide when it is appropriate to use a tutorial versus some other form of documentation. Important considerations include the nature of the tutorial as a learning activity, and its narrow focus on achieving a very specific goal.

Selectivity in Choosing Material

In determining which procedures warrant tutorials, Barker asserts, one must rely on their user analysis. In doing so, a documentation writer will likely build tutorials based on the most common scenarios that their users will encounter.

The Elaborative vs. Minimalist Approach

Barker defines the elaborative approach as a theory of teaching that emphasizes comprehensive coverage of a topic, with the help of “summaries, explanations, examples, and articulations of goals and objectives”. Some research has shown that this approach can help users apply what they have learned to real-world situations more readily. This approach is consistent with Barker’s six principles of lesson design:

1. Instruction results in articulated skills.
2. Skills transfer capability to real-world performance.
3. Steps should present skills in a logical, cumulative structure.
4. Highly specific instructions work best.
5. Give practice and feedback at each skill level.
6. Master one skill before going on to the next.

Barker describes the minimalist approach as one that expects a certain impatience from documentation users, and attempts to serve them accordingly. He quotes John Carroll’s observations that documentation users often tend to:

• Forego introductory or orienting documentation and dive right into interacting with the program
• Skip information that does not appear immediately relevant
• Resist restrictive instructional strategies and assert creative control over the learning process

Barker also references Carroll’s four principles adhered to by minimalist manuals:

1. Choose an action-oriented approach
2. Anchor the tool in the task domain (workplace context)
3. Support error recognition and recovery
4. Support reading to do, study, and locate

Ultimately, the decision to use an elaborative, minimalist, or hybrid approach depends on the situation and the professional judgment of the documentation author.

Barker concludes the chapter with a glossary of terms and a checklist for evaluating tutorials. He also includes a number of tutorial analysis exercises.