User Assistance Walkthroughs: Helping Best Practices Emerge

The User Assistance Walkthrough

A major difference I have found between UX walkthroughs and user assistance walkthroughs—specifically those for reviewing Help content—is that the team is less diverse for Help walkthroughs. Help walkthroughs generally include information architects, information developers, and editors. One reason for this less diverse set of participants is that such walkthroughs typically get down into the weeds of technical writing at a level that would induce comas in stakeholders. For example, there might be a ten-minute discussion over “clicking” versus “if you click” versus “when you click.” Coders avoid such discussions for the same reason writers avoid discussions about Java classes and methods. Each is happy that smart people in another specialty are worrying about such things and content to have them do so.

User assistance walkthroughs achieve diversity of viewpoint by having multiple writers participate—sometimes writers from different product teams. Such cross-team participation offers the added benefit of enabling writers to shape consistent approaches across all user assistance products and synthesize best practices.

Another difference between UX and  user assistance walkthroughs is user assistance is driven less by formal requirements and use cases and, instead, more by the information requirements a given user interface presents. For example, the Help for a well-designed form might be entirely different from the Help for a less elegant design—even though the designers of both forms created them in response to the same set of requirements and use cases.

With these differences in mind, here is a blueprint for a user assistance walkthrough:

• Review the user interface the writer is documenting and how a user can access the user assistance. The walkthrough should focus on whatever aspects of the user interface relate to a user task or goal—either a screen, window, or page or a series of windows or pages. Describe the task or goal. Discuss what the typical information gaps might be, what baseline knowledge or skills a user should have, and so forth. In short, have an idea of why a user would go to Help from the user interface you’re discussing.
• Step through the Help file as a user might. Review the usefulness of the information architecture. For example, can a user get to the most needed information easily or must the user drill down several levels? Are the links within the Help file useful for the task at hand, or do they take the user to unrelated sections of the Help?
• Review how the writer is handling different types of information and whether they are consistent with other applications. For example, if each topic opens with a short description, are different writers handling descriptions in similar ways? A walkthrough is an excellent way of catching inconsistencies. For example, one writer might be starting a short description by saying “Use this page to…” while another writer has been saying “This page allows you to….” Walkthroughs not only catch these kinds of inconsistencies, they let the team decide which of the available alternatives should be the best practice across applications.
• Review the writing for effectiveness and compliance with existing guidelines. The walkthrough is a great opportunity for experienced writers to teach less experienced writers and for editors to enforce style guidelines.

Guidelines for Writers

These guidelines can help writers elicit good feedback during user assistance walkthroughs:

• Avoid being defensive. However, you do need to explain decisions, so other participants have the benefit of the analysis you have done. Here is a good pattern for writers to use if challenged:
  • Validate the input. For example, “Good observation,” or “Interesting point.”
  • State the goal you were trying to achieve. For example, “The problem I’m trying to solve is novice users might not see this tip as an alternative, but instead think it is a required step.”
  • Provide the rationale behind the current solution. For example, “So I thought starting with the conditional statement ‘If you are using…’ might make that more obvious.”
  • Ask for a suggested solution. For example, “How would you handle it?”

Note—When someone points out an obvious error such as a misspelled word, just say, “Thanks for catching that” and make the correction. There is no need to bemoan that you cut and pasted from the previous owner of the document or how overworked you have been. Your co-workers know that you know better and that you would have caught it. Don’t trivialize their moment of value.

• If what you wrote and what someone is suggesting would be equally good, make the change! There is an adage in change management that says, if you would influence others, you must first allow others to influence you. Accommodating the input of others nourishes a culture of collaboration. Embrace any opportunity to lose small arguments if you want to win big ones.
• Make changes in real time. Have the authoring tool running and the source file available. Reword problematic sections then and there, so the team can agree on the rewrite. When feasible, regenerate the Help topic, so the team can see the change as it would appear to users.

Guidelines for Participants

These guidelines show how to participate effectively in user assistance walkthroughs:

• Defer judgment about a writer’s skill or knowledge when reviewing an early draft. There is creative trust on the part of the writer in showing you early drafts. It’s like you dropping in on somebody’s house uninvited; checking for dust on the mantel or commenting on the dishes still in the sink would be in poor taste.
• Point out inconsistencies between different approaches as simple facts, not judgments or disagreements. For example, if the approach a writer took to labeling tables in the Help you are reviewing is different from the way you’ve been labeling tables, there is a big difference between saying “I haven’t been labeling my tables the same way you have,” and saying “I don’t like the way you handled the labeling of tables. Let me tell you how I do it.” The former is more likely to lead to a rational discussion of the different approaches and an informed decision by the team.
•  Discuss the writing in the context of how you are processing it, not in ways that judge the writer. Avoid saying, “This is confusing,” when you could make the more objective observation, “I had to read this three times before I got it,” or “I don’t understand what this is telling me to do.” More often than not, when I make such an observation, the writer explains it to me in a way that gets to the point more effectively. Then someone on the team invariably says, “That’s great, can you say it that way in the Help?”
• Educate walkthrough participants about what style guidelines might apply if your role is that of an editor. Even in the presence of well-established guidelines, writers often fail to research them or forget to apply them. In essence, the editor serves as the “rule memory” for the walkthrough team’s collective brain. However, the editor should not state observations about guidelines as discussion-ending dictates. During the initial discussion, an inconsistency should merely be an observation such as, “The current guideline says items in a bulleted list should be in lower case unless items are sentences, which should be capitalized.” The team might discuss changing a convention or improving a guideline.
• Update and disseminate guidelines and best practices that emerge from walkthroughs. It is also the responsibility of the editor to capture and publish such information.

Guidelines for the Facilitator

Following these guidelines can help facilitators lead effective user assistance walkthroughs:

• Set up the walkthrough environment early. Make sure you have access to all of the files you will show or documents to which you will refer. When possible, have the target application running.
• Keep the focus on users and their context. Writers love to argue the finer points of grammar and usage. Don’t let the length of an argument become disproportional to its impact on the user experience.
• Have a plan for the walkthrough. Your walkthrough should preferably start with an understanding of context and the target user.
• Be flexible about your plan. Accommodate the needs of participants to explore areas you had not included.
• Try to get consensus. However, if all the facts are on the table and participants have made all their arguments, but still disagree about a convention, let the editor decide.

Note—As much as I have tried to get teams to start with the larger issues and work down into the weeds, I have found that people’s natural tendency is to start in the weeds. Writers focus early on word usage, typographical choices, spacing, and the like. Don’t fight it. Just don’t let it get in the way of more important discussions such as the usefulness of content, flow, and the architectural decisions that will shape the overall Help system.

Conclusion

As with any meeting that encourages open feedback and criticism, walkthroughs can elevate the stress level of the participants and especially the writer whose work you’re reviewing. Walkthroughs rely on a culture that values openness to collaboration and the quality of the resulting product. The best path to demonstrating the value of walkthroughs is letting writers experience how their own work improves when exposed to this process. Management cannot mandate a culture that values collaboration, rather individual contributors must collectively nurture such a culture. The guidelines this article has presented will help shape useful behaviors, but ultimately, a team must decide what it values more: individual excellence or collective achievement.