User Assistance Walkthroughs: Helping Best Practices Emerge

User Assistance

Putting Help in context

A column by Mike Hughes
July 23, 2007

In my previous job as a UX designer, I learned the value of collaborative design walkthroughs. During walkthroughs, the UX designer would step through a user scenario—using the wireframes or mid-fidelity prototypes—with a cross-disciplinary team comprising product management, other UX designers, business analysts, developers, product testers, and technical communicators. The motivation for doing these walkthroughs was to reduce the amount of churn around product requirements that was occurring during coding and testing. No matter how well-written a requirement or use case was, it wasn’t until stakeholders could interact with a design within a tangible context that the full implications of a requirement or its lack of sufficient specificity became evident.

Champion Advertisement
Continue Reading…

Beyond the benefit of clarifying requirements and gaining agreement among the team that a design met the requirements, I have found that walkthroughs have a deeper, even more valuable impact as a social mechanism for creating and distributing organizational knowledge. Walkthroughs:

  • let designers share the rationale for design decisions they make
  • identify common design approaches—across designers and even across design teams
  • enable the development of consistent methods
  • subject design approaches to collective scrutiny, honing them into best practices
  • get organizational buy-in for those best practices

My current focus on user assistance as a component of the user experience has reinforced my respect for the walkthrough as an essential design activity—this time for information designers and information developers. Although the lessons I’ve learned from doing UX design walkthroughs apply to user assistance, user assistance has some unique requirements and dynamics that warrant this article’s special focus.

The Elements of a Walkthrough

A walkthrough is a review of a user interface within a context in which a user might experience it. However, what is typically lacking is users. A walkthrough is not a replacement for real user input through contextual inquiries or usability testing. Instead, it is an early design activity that lets a team scrutinize design approaches by bringing multiple perspectives into a context-rich review process. A design walkthrough typically includes the following elements:

  • a review of the problem or requirements the design addresses
  • demonstration of the design through wireframes or prototypes
  • questions about and critiques of the design approach
  • exploration of alternatives

Physically, a walkthrough requires either a conference room, with the capability of projecting wireframes or a prototype, or an online meeting service that supports desktop sharing, such as NetMeeting or WebEx. It is also very helpful if you can provide a way of editing and redisplaying the wireframes or prototype as you incorporate suggestions. Remember, one of the reasons walkthroughs are beneficial in the first place is ideas that sound great sometimes flounder when implemented within the real constraints of a user interface.

Most importantly, a walkthrough requires a culture and facilitation style that say, “It’s okay to share half-baked ideas early.” This can be a difficult value to foster where creative pride and egos are on the line. I believe this is less of a problem with UX designers, who typically work in a “let’s rough it out on a whiteboard” culture, than it is for technical communicators, who are more likely to write in solitude and want to polish their copy before sharing it. Certainly, I am not advocating that writers turn off their spelling checkers or do a walkthrough before they’ve made an effort to write effectively. But there is little value to perfecting prose that might turn out to be the wrong prose for a user’s situation or in adjusting the placement of a graphic, pixel by pixel, only to find the graphic is too technical for the targeted user. Typically, walkthroughs catch things a writer might never have changed, even after the most rigorous of self-reviews.

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.


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. 

UX Designer at TSYS

Atlanta, Georgia, USA

Mike HughesIn his role as User Experience Architect for IBM Security, Mike’s professional focus is on designing usable user interfaces that accommodate the user as learner. Previously, as User Assistance Architect at IBM, Mike identified tools, methods, and standards for integrating the content and delivery of user assistance, including documentation, Help, elearning, and training. He was formerly Lead UX Designer for CheckFree Corporation, where he instituted their User Experience Research and Design Center. Mike has a PhD in Instructional Technology from the University of Georgia and a Masters in Technical and Professional Communication from Southern Polytechnic State University. He is a Fellow with the Society for Technical Communication and a Certified Performance Technologist through the International Society for Performance Improvement.  Read More

Other Columns by Mike Hughes

Other Articles on User Assistance Design

New on UXmatters