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.

Campbell Chapter 2 - Where Do I Start?

Campbell begins this chapter by discussing the importance of not skipping preliminary steps when trying to write an effective document.

Next, Campbell goes on to address the four steps to development, which is the preparation prior to drafting. The four steps are:
• Planning
• Analysis
• Research
• Prewriting
The time it takes to get through each of these steps depends on both the writer and the document. Campbell also notes that each step is needed in the correct order to make a successful document.

Campbell then begins her in-depth description of each of the steps, starting with planning. She says that a plan must be developed, and it is normally should be done in writing. The plan can be simple, but it should always be completed before any actual writing occurs.

The first part mentioned by Campbell is to set a schedule. She notes that schedules can be as simple as a piece of paper, or for more complicated projects, a Milestone or Gantt chart can be used. These charts show time frames for each step, and can also include personhours, assignees and overlapping steps. Campbell makes a point that schedules should not be skipped because without them, a deadline will surely be missed.

The next part of planning that Campbell discusses is using a team. She notes that because of the nature of some projects, a team works better than a single person. Team writing has both benefits and disadvantages like any team activity. Campbell says that success depends on good organization and clear communication.

Then, Campbell goes on to discuss being realistic, which is the last part of planning. She says you must again think about time frames, team members, possible conflicts and “brick walls,” and consider if they are realistic goals. Frustration is largely avoidable with realistic planning.

The next step in the four steps of development is analysis. Campbell describes analysis as a “realistic look at the audience, the assignment, the context in which it’s been made, how much and what types of research are required, and the conditions under which you’ll have to work.” She says to begin an analysis with the “what” and “why” of the project. Look at who is requesting the project, examine the reasons for the request and finally look at the nature of the project.

Campbell says that after the nature and reason for the request is known, one should be sure to understand the goal and the desired end result of the finished policy or procedure. If the goal of the project is not clear, this is the time to go back to the requestor for more information. Campbell states that you can’t help readers understand the importance of the policy or procedure if the writer doesn’t understand it.

Another part of analysis that Campbell notes is audience. She says that the more one knows about the audience, the better choices the writer can make in content, wording, format, and design of the document. The experience, education, preferences, expectations and attitude of the audience should all be considered.

Campbell then goes on to discuss the other elements to be analyzed when starting a project. She writes about conditions of document use, the urgency of the document, the impact the document will play on the organization and the project conditions. The analysis step is concluded by going back to the requested with updates. Campbell notes that writers have to sometimes fight for the resources to do the job, and these must be clear to the requester.

The third step to development is research. Campbell says that when this stage is reached, the writer is taking the first real action on matters of content. The amount of research is determined by the analysis of the project.

Campbell says that one should start with the most difficult, complex information, since it takes the longest to study and understand. She says to resist the urge to start with the easiest research first. Starting with the difficult research gives you time to ask questions, get clarification and resolve misunderstandings.

A writer should talk to content experts, but not stop there. Campbell suggests talking with anyone that holds information about the project. She says to talk to both internal and external people to gain insight about the project. To properly interview these people, the normal etiquette of informational interviews should be observed. One should have a list of prepared topics and questions, and the interviewee should be informed about the reasons of the interview. Campbell emphasizes the need to take notes. She says that a standard form of notes is good when interviewing a large number of people. These notes are the foundation of your document’s content, so Campbell says to take them carefully and accurately.

Campbell goes on to discuss soliciting information in writing, which is sometimes necessary if individual interviews aren’t feasible. She says to keep the solicitation as simple as possible and to remember that written requests are generally less effective.

Campbell then goes on to explain reading and studying. She says that when interviewing and surveying are not sufficient or possible, one should explore books, articles or trade publications that contain current, relevant material. Campbell suggests looking through organizational files, suggestion forms or comments during meetings, current policies and procedures, libraries and the Internet.

A final note Campbell makes about research is to concentrate on the critical information because a writer seldom has time to locate everything that’s out there on a given subject.

The final step Campbell discusses is prewriting, which is the missing link between the preparatory steps and the actual document. She says it organizes the material and speeds the drafting. Before drafting begins though, the material needs organized. A writer should have accurate and complete content, good organization, and logical flow before they start writing.

Campbell notes that a mind-map is a simple way to get all possible content concerns out on the table before the writing begins. She says the mind-map works better than starting with an outline because often content gets left out in a structured, numbered list. Mind-mapping eliminates the rigid list and lets the random, creative side thrive.

Campbell concludes this step and the chapter by stating that after the information that should be included is decided, it must be placed in the proper sequence. She says to create an outline of the mind-map by combining key words, phrases, sentences or paragraphs. The material should be put in a sequence or flow that’s logical to the reader, not necessarily the writer.