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.

Campbell - Chapter 1 Summary

Writing Effective Policies and Procedures: A Step-By-Step Resource for Clear Communication

Nancy J. Campbell

Chapter 1 - What’s a Policy, What’s a Procedure?

In Chapter 1 of Writing Effective Policies and Procedures: A Step-By-Step Resource for Clear Communication, Nancy Campbell begins by defining policies and procedures, and explaining why they are important. She goes on to describe the different forms and formats that policies and procedures may take within an organization. Throughout the chapter, practical tips are offered for crafting policies and procedures effectively, along with pitfalls to be avoided. She concludes with a summary of the chapter and some useful lists and tools for policy and procedure formation.

Campbell divides the content of the chapter into 8 main sections.

Why You Need Policies and Procedures

Policies and procedures provide users in an organization with the information they need to do their job, preventing chaos and frustration. They tell users “what the organization wants done, why it wants it done, and how to do it” (1).

Policies

Campbell defines policies as a form of position statement. As “clear, conscious decisions about its own standards and principles of operation,” policies are meant to guide organizational action (2).

Because policies cannot, and often should not, attempt to cover every conceivable organizational decision, they include some degree of ambiguity. Campbell lists 3 factors that influence the degree of ambiguity allowed for within a policy. These include: the ability of users to understand and cope with the policy, the manager’s competence with the policy and willingness to enforce it (which may necessitate additional training), and the way in which the organization views the issue and its importance.

Procedures

Procedures are “action oriented” and represent a “protocol for implementation, the ‘how to’.” (3). They outline steps in a process in order to effectively guide users through a given task. Procedures often describe consequences for noncompliance, such as damage, loss, injury, or discipline. These help to convey the seriousness of the issue and a users’ responsibility to comply.

Campbell illustrates the issue of ambiguity in policies by giving an example of a highly ambiguous policy. Procedures are typically less ambiguous than policies, but may still include ambiguous elements. This ambiguity may be necessary in order to allow for professional judgments on behalf of its users.

The amount of ambiguity contained within a procedure is a subjective decision on the part of its author. Campbell goes on to assert that total objectivity is an impossible goal, but good procedures should encourage users to exercise “sound business judgment” within the framework of the procedure set forth (5). This requires that policy and procedure writers determine what situations require subjective judgment, how much subjectivity is called for, and what standards or parameters should guide that judgment.

When You Need Policies and Procedures

Policies and procedures are a means to an end, and should serve to accomplish a specific purpose. They can often be a reactionary response to an unforeseen situation. In these cases, policy and procedure writers should pause to ask the following questions before they “jump into the writing fray:

· Has such an incident ever happened before?

· Is it really likely to happen again?

· Is this an isolated, once-every-twenty-years occurrence?

· Are the consequences of the mistake so serious (financially, legally, or operationally) that you need to be sure it never happens again? (6)”

Situations such as personnel, health, and safety demand clear policies and procedures. They are necessary in virtually any situation that is both important, and requires clarification.

Important issues are those that affect the audience or the organization. These can include:

· Efficient use of resources

· Schedules

· Customers

· Finances

· Image or reputation

· Health and safety

· Productivity

· Marketing

· Staffing

· Liability and other legalities

Users are impacted by any issue that affects “their personal circumstances or well-being,” such as:

· Benefits

· Hours

· Working conditions

· Job security

· Stress

· Satisfaction

· Status

· Personal principles

· Personal goals

· Family

In recognizing important issues, it is necessary to look at the issue from all perspectives, and never underestimate different interpretations.

Many important issues require the clarification which a policy or procedure provides. This is important when the subject is:

· Lengthy

· Complex

· Routine but essential for successful operations

· Affects the reader’s ability to function

· Affects the reader’s status

· Affects the reader’s personally

· Involves significant change or high volumes of change

Sometimes, people simply need a reference or reminder to help guide them through a particular process.

Written vs. Unwritten

In most cases, it would be impossible to document every decision and procedure that a person will be required to make when working for an organization. “Organizational culture, like dress and hygiene” is an example of a scenario often governed by unwritten rules. A topic should remain unwritten if it:

• Involves organizational culture and norms

• Cannot be enforced consistently
• Could possibly be offensive or intrusive
• Is simplified

Policies and procedures that are codified in writing should always reflect:

• Accountability
• Clarity
• Consistency
• Critical importance
• Documentation
• Health or safety
• Legal liability
• Licensing or regulatory requirements
• Serious consequences

Often times, as an organization “grows, change increases, or complexity arises,” it is necessary to transform policies and procedures that were once unwritten into a written form.

Some reasons for doing so include:

• Accidents
• Changes
• Complaints
• Confusion
• Cost overruns
• New laws or regulations

What to Include in Policies and Procedures

As a policy and procedure writer, you need to make a judgment call as to what your audience needs to know, and what you want them to know. When uncertain as to what should be included, you can ask yourself two questions: “Who says so?” and “Why?”.

What Readers Want to Know

Readers of policies and procedures are interested in learning two things: what the policy or procedure will do FOR them, or TO them. It is important to identify with your reader by offering reasons for the policy or procedure and assigning responsibly for compliance. Campbell suggests you “use the writer’s motto: WIIFT…What’s in it for Them?”

Level of Detail

It can be challenging to determine the level of detail that a particular policy or procedure should include. It needs to be sufficient to accomplish its goals, yet remain appropriate to the subject and the audience. When dealing with complex subjects, one should take the experience level of the audience into account and perform a thorough audience analysis to help make good decisions concerning depth of detail.

Manuals and Handbooks

When dealing with multiple policies and procedures, for the sake of convenience it is common to combine them into a manual, handbook, or user guide. Campbell defines these products differently based on certain characteristics. A manual implies restricted circulation, while a handbook implies general distribution. By organizing policies and procedures into a logical structure, their creator will promote increased use among users, thereby increasing their overall effectiveness.

Chapter Summary (and Tools & Resources)

Campbell concludes with a summary of the chapter and several lists and tools that writers can use to create more effective policies and procedures.

Barker Chapter 1 - Understanding Task Orientation

Barker begins this chapter with a series of examples showing effective software documentation. He notes that these examples both explain and show the connections between the user’s professional work and the computer program. Scenarios, examples, and page layout can all contribute to this explanation, and according to Barker, any manual that helps the user manage and communicate information related to his or her task can be described as “task oriented.”

Barker then gives a detailed list of techniques to create a manual that helps users solve a complex task, including:
• Emphasizing problem solving – use introductory paragraphs that preview not only the steps to follow, but the goals and objectives of their software work.
• Providing task-oriented organization – Organize a manual or help system in a way that matches the kinds of tasks a user will perform.
• Encouraging user control of information – The manual should show users how to make key decisions, supply key information or determine key outputs (the user decides what the program does for them).
• Orienting pages semantically – Arrange the elements of the page meaningfully, according to elements of the job the user needs to perform.
• Facilitating both routine and complex tasks – Routine tasks include repeatable tasks that are easily represented by conventional procedures, while complex tasks are not performed the same way every time. The more you can help users apply software to complex tasks the more users will value your manual.
• Designing for users – Manuals should be designed for what the user needs and not from a template. User-drive design should allow users to find what they need, understand what they find, and use what they understand appropriately.
• Facilitating communication tasks – Communication tasks are defined as, “tasks that require the use and manipulation of information to coordinate workplace activities.” Document designers can help users see the why behind the program features by analyzing what kinds of information users need and how they communicate, and then identifying those program features.
• Encouraging user communities – Users often need encouragement to rely on other users of the program; task-oriented documentation encourages users to identify and get help from others.
• Supporting cognitive processing – The task-oriented manual uses principles of knowledge representation, parallelism and analogy to convey software features and applications to workplace tasks.

Next, Barker provides a definition of task orientation, stating that it is “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.” He also states that exploring the theory behind task orientation can help with documentation design and provide a foundation for techniques discussed later in the book.

Barker goes on to describe both the default manual and user. The default manual has the following characteristics:
• Covers the features of the program
• Implicit role of technological ignorance imposed on the user
• Ignores the user’s workplace use of the program
• Assumes one way of learning
• Overly simplified approach to program operation
The default user has the following characteristics:
• 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

Barker then notes that people often resist using computers and software because
of the inherent complexities of abstraction and information overload.

Next, Barker describes the characteristics of a task-oriented user, which include:
• Challenged by redefined work activities
• Conceptually oriented
• Aware of user communities
• Self-managing
• Supplied with resources

Barker continues the chapter by discussing the different forms of software
documentation, which include tutorial, procedural and reference. Tutorial documentation has the following characteristics:
• The user motivation is to learn
• Intention to teach the features of the program
• Relationship of teacher and learner
• Defines the task through scenarios, cases, examples; narrative structures
• Focus on basic actions
Procedural documentation has the following characteristics:
• The user motivation is to perform routine tasks
• Intention to guide through step-by-step procedures for using the program
• Relationship of guide and mentor
• Defines the task through chronological, step-by-step structures following the menu of choices or fields in a pane or screen
• Focus on operations organized around workplace actions
And, reference documentation has the following characteristics:
• The user motivation is to obtain information “about” the program
• Relationship of resource and client
• Lets the user define the task
• Focus on the program

Barker concludes the chapter by discussing the processes of software documentation. He says that to provide useful task-orientated documentation, one must look at the process of writing and find ways to learn about users. You don’t have to know the user if you are writing a default manual, but to have an effective task-oriented document, you must know the user. The process begins with the analyzing the users instead of the program. The process of writing and testing starts with the exploration of needs, and then requires constant involvement of the user. The process is called a usability process and is defined by the following stages:
• Planning Stages
o User interviews to find out what actions users take using the software
o Focus groups to find out user needs and organized constraints
• Development Stages
o User reviews to see how well the manual fits with workplace tasks
o User lab tests to gauge accuracy of manual and help information
o User field tests to gather additional information about workplace users
• Evaluation Stages
o User field evaluation to assess the overall value of documents
o User usage reports to help adjust writing and research processes for subsequent manual releases

Welcome to the English 477577 course blog

Welcome!

You have found the course blog for English 477577 at Minnesota State University, Mankato for fall semester 2007. We will use this blog to discuss our readings for the semester.