Barker - Chapter 5 - Analyzing Your Users

Writing Software Documentation: A Task-Oriented Approach
Thomas T. Barker

Chapter 5 – Analyzing Your Users

Intro

Barker begins the chapter by giving an overview of what user analysis entails and why it is valuable. User represents the “basic research phase of the documentation process”, and involves “contact with persons who might use the software that you want to document. It involves inquiry into eight areas:

1. Tasks and activities the user will perform
2. User’s informational needs
3. User’s work motivations
4. Level of the user’s computer experience
5. User’s knowledge of the program’s subject matter
6. User community
7. User’s learning preference
8. User’s usage pattern

The answers to these questions will assist throughout the documentation process, informing the goals for the documents and what they will cover.

1. Choose Users Carefully

You begin this process by listing every potential type or group of potential users of the software as possible. You can then narrow down this list to those whom represent typical users and with whom you can form a working relationship throughout the documentation process. This selection process should involve consideration of each user’s unique culture.

After assembling this list of users, you will conduct a series of interviews with these individuals to build a list of common job tasks that would benefit from documentation.

2. Anticipate Transfer of Learning: Study Users Before and After Tasks

You should begin by determining the activities of users, “without the benefit of your program”. When you understand about the duties and skills of your users, you can craft your documentation in such a way that facilitates the transfer of these pre-existing skills to the operation of your software.
It is also important to build up a repository of tacit knowledge about users, which includes all of the small facts, attitudes, artifacts, interactions, and values that guide them in their job duties.

3. Research Professional Behaviors

In situations where direct user contact is impossible or insufficient, it is possible to research professional behaviors to construct a “mock-up of the user”. There are many resources for learning about the job duties of individuals in a particular position or industry, including occupational guides, industry-specific guides, placement services, or company job descriptions.

4. Write Use Cases

Use cases are descriptions of typical job scenarios, based on the tacit knowledge that comes from uncovering the “motivations, behaviors, values, and knowledge pertaining to your users that might not be visible on the surface.” By employing use cases in your documentation, you provide role models for your users. Use cases can also be included in the documentation plan to illustrate the types of activities that will be supported.

Work flow diagrams, which graphically depict organizational processes, are often a useful accompaniment to a use case. Barker also suggests that you should be mindful of your limited resources, and restrict your documentation accordingly.

5. Plan Interviews Carefully

Effective software documentation should “encourage [users] to learn the features of the program and put the program to useful work.” To this end, interview questions should involve users in the whole documentation cycle, using a usability approach.

Familiarity with the developers of the program and the program itself should help inform the questions you will have for users. Investing time in an interview plan can greatly increase their productivity. General steps for interview planning include:

1. Do preliminary research into the user’s job and programs already in use.
2. Review the software program and indentify the issues.
3. Establish the scope of your interviews.
4. Make a list of interview questions.
5. Get permission.
6. Set up and interview schedule.
7. Plan a follow-up.

Barker also recommends attempting to assess the verbal style of the users and reflecting it throughout the interview process to solicit better answers.

In addition to interviewing, observation can be a useful tool for gathering data about your users. This involves shadowing users at their place of work and recording their various actions, while taking care to avoid:

· Getting too involved – such that you distort their activities.
· Not getting involved enough – such that you focus on the wrong details.

Questionnaires are also valuable in that they allow you to gather information from a variety of users, increase the chance of identifying unique concerns, and identify wide patterns of use. For best results, these questionnaires should make use of open-ended questions, include clear instructions and plenty of room for filling in responses, and avoid negatively-worded questions.

6. Involve Users in All Phases of Project

A full user analysis should involve users in every stage of the documentation process, including writing, reviewing, and testing. This results in many benefits, including:

· Increased accuracy
· More appropriate information
· Increased usability
· Improved relationships

The relationship between the documentation writer and the users is an important one. Including them in the process yields valuable information regarding their specific situated action in the organization. This allows you to become a user advocate, bridging the gap between the software program’s users and developers. This relationship will also benefit from embracing the work culture of the users.

Conducting focus groups is another way to involve users in documentation, and are a good way to spark new ideas. Tips for conducting a successful focus group include:

1. Locate potential participants.
2. Develop and administer a telephone screening questionnaire.
3. Confirm invitations in writing.
4. Draft open-ended questions and follow-up questions, then revise.
5. Plan any hands-on activities.
6. Make reminder calls.
7. Pilot-test the questions with one or two group members.

Encouraging user participation in this way helps “extend the possibilities of user-centered design.”

7. Identify Document Goals

It is important to communicate your documentation goals early in the process. These consist of statements expressing specific objectives describing how the documentation will encourage users to learn the program and use it effectively. “The clearer your objectives,” states Barker, “the better the chance that you will achieve them.”

8. Tie the User Analysis to Documentation Features

It is important that the features that you document are chosen based on specific user needs. By tailoring this information to specific users, a more usable document results.

Discussion

User analysis is of central importance when composing task-oriented documentation. It incorporates the users’ workplace context, personal needs, organizational goals, work culture, and many other factors. This can assist you in a number of ways, such as by revealing ways in which users will use the software, providing scenarios and examples for use in tutorials, and identifying potential topics for testing, among others. Ultimately, a well-done user analysis will help “unify your document set”.

Software use is always situated in a user’s workplace and cultural context. Effective documentation will take this into account, and reflect “the user integrating the program instead of just the program.” Eight questions that help provide this tacit knowledge include:

1. What tasks will the user perform with the program?

Knowledge of job roles provides a starting point in describing user actions. Workplace activities exist in a context of information. Barker suggests focusing on a few key tasks to use as cornerstones within your documentation.

2. What are the user’s informational needs?

Often, software users may require some knowledge that is outside the realm of the program itself in order to use the program effectively (e.g. graphic design principles for a user of page layout software). It is useful to identify any such information and direct your users to the relevant resources.

3. What are the user’s work motivations?

Awareness of how users’ tasks shape their information and communication needs will help you to identify users’ underlying motivations. Interface elements should therefore take this awareness into account, and be arranged into “meaningful sequences leading to an objective” that is of value to the user.

4. What’s the user’s range of computer experience?

There are many differences between novice, experienced, and expert software users. It is important to pay attention to these differences and target your documentation to the learning patterns of the appropriate audience, or multiple audiences, when necessary.

5. How much does the user know about the subject matter of the program?

Subject matter knowledge influences the amount of supporting detail required when describing operations. This professional knowledge is also referred to as domain knowledge.

6. What’s the user’s workplace environment?

Various forms of user communities can often provide a great deal support to software users. These include help forums, special interest groups, newsgroups, user groups, web resources, newsletters, third-party documentation, FAQs, web rings, and mailing lists. You should strive to direct your users to these resources when appropriate.

7. What’s the user’s preferred learning preference?

Individuals accumulate knowledge in different ways based on a variety of factors. Whether the information is being delivered by an instructor, manual, or computer-based system, it is important to take into account factors such as the learning setting, the source of information, variations in information delivery, and the various forms of media used.

8. What’s the user’s usage pattern?

Usage patterns describe how users interact with the software over time. These can be: regular – involving daily use, intermittent – regular and frequent but at irregular intervals, or casual – an immediate need for use exists, but with little or no formal training yet received.

Barker concludes the chapter with a glossary of terms, a checklist for performing a user analysis, and some case studies with which to practice.