Good Help is Hard to Find

One of the most fundamental rules of user experience on the web is that developers are rarely qualified to evaluate it. As developers, we know far too much about the web in general, and intuitively grasp details that mystify people who spend their days contributing to society in other ways. For this reason, it’s all too easy for us to build websites and applications that are hard to use. Good user testing during the development process can mitigate the problem, but in many projects, the testing budget is limited if present at all.

A person who has trouble using a website to accomplish a task will quickly grow frustrated. At best, a frustrated person will leave the site; at worst, they will complain about the experience to others. When our users hit a roadblock within a website or application, effective help content is our last chance to transform a negative experience into a positive one.

If content is the red-headed stepchild of web development, help content is even less popular. No one wants to create it or maintain it. When it does exist, it’s frequently hard to find, poorly written, and not terribly helpful. But done well, help content offers tremendous potential to earn customer loyalty.

Best practices#section2

Effective help content is a greater challenge than we might assume. Developing a strategy means thinking beyond writing simple instructions to accomplish a task.

Tone#section3

First, we need to understand that anyone who’s reading help content is already frustrated. Our goal is to de-escalate those feelings. The tone must be sensitive, not condescending. Never blame the customer for problems. Consider the following scenario: A web application requires users to click a confirmation link in an e-mail before allowing them to sign in, but the e-mail never lands in the user’s inbox. Imagine reading the following help message addressing the issue:

This language, slightly modified from real-world help text, could certainly be worse, but note how possible explanations assume the user’s at fault: “your e-mail program” and “if you still can’t find it.” This text strikes a defensive tone. The issue may well be on the user’s end, but stating it doesn’t make them feel better. Consider this alternative:

This message is much more conciliatory. It implies that it’s the web application’s responsibility to get an e-mail to the user, not the user’s responsibility to find it. It also concedes that the user might have been wise enough to check the spam folder. Finally, it offers a way to solve the problem immediately, not just a link to another page.

When developers write their own help content (or even error message text), it’s easy to take a condescending tone because we’re so close to the subject matter. If at all possible, help content should be produced by a writer familiar with the usage of an application or website but not necessarily intimate with its inner workings.

Brevity#section4

Help content does not exist for its own sake. It supports someone who tried, but was unable to perform a task. People follow the path of least resistance to a goal, and if task instructions take too long to process, they’re likely to abandon the quest. Help content should be brief, containing just enough detail to address the problem and get the user back on task.

Curation#section5

Help content references the form and function of an underlying application. This dependency may not be obvious to developers, who are focusing their efforts on the application itself. Designate someone to take responsibility for evaluating changes to determine if they affect the help section. For example, a simple application interface change has far-reaching consequences if your help content includes screen captures. If a link that previously said “Back to listings” now reads “Cancel,” you will need to update dozens of references. Once help content gets out of sync with the website or application it references, it becomes decidedly unhelpful. A website’s content strategy—or an application’s maintenance workflow—must include a procedure to review and update help content as the source material changes.

Embedded help#section6

Help content can be rendered in many ways, but if possible, embedding it directly within the feature it serves is almost always the best choice. When help is offered in context, affordance is high: That is, the help is obvious to the user. Even better, context-based help is the least disruptive to workflow, as it doesn’t require the reader to view a separate page. Additionally, it doesn’t rely on screen captures or illustrations, so it’s easier to maintain. At a technical level, embedded help should be tightly coupled to the code that it supports, making it much less likely that changes to the application will creep in independently.

Inline Instruction#section7

Embedded help can be as simple as inline guidance on what to enter in a web form, as seen below in Twitter’s account signup process. Here, some explanatory text appears parallel to each form input as it receives focus.

Twitter’s signup page displays format requirements next to the password field.

This approach works well for simple instructions or term definitions—items that likely apply to all users—but it isn’t practical unless the help content is extremely short.

Tooltips#section8

The “tooltip” pattern is another unobtrusive way to embed help. With this approach, a link or icon indicates help is available, but the details are only revealed on mouseover. The effect can be achieved in most web browsers by using the title attribute of an anchor or image element. However, this technique doesn’t offer any control over text formatting, and there’s often a delay between the mouseover action and content rendering, which may be undesirable. Consider CSS and/or JavaScript to create more sophisticated tooltips.

Like inline help, tooltips should be tightly coupled with application content and have strong affordance. An additional advantage is that they keep content out of the way for those who don’t need it. However, they are still only useful to present short text segments with minimal styling. Also, this pattern may not work well outside a traditional desktop browser—in a touch interface, for example.

Realtime analytics software Chartbeat uses tooltips in its dashboard display to explain the meaning of individual metrics:

This tooltip defines what Chartbeat considers an active visit.

Modal Dialogs#section9

With modal dialogs, you can present longer or more complex content (including illustrations, for example) without taking a user out of the current workflow. Consider that web interaction often occurs through forms. If a user partially completes a form and needs help to finish the task, a standard link to content on another page can present a major problem. Unless the link opens a new window, the person loses everything they’ve typed into the form. And, opening a separate window introduces additional complexity that we’ll consider shortly. Modal dialogs bring compromise, allowing us to overlay longer content on the current page. This pattern does come with some caveats, however. It depends on JavaScript and thus needs a fallback behavior when scripting is unavailable. And although a modal dialog may be able to hold more information than a tooltip, content length is still limited.

In this example, Facebook uses a modal dialog to answer a common question on its signup page:

Facebook’s modal dialog explains why users must supply their birthdate when signing up.

Non-embedded help#section10

Sometimes, help content must be lengthy to be effective. When this is the case, the content strategist and developers face a number of important decisions. How will users interact with the information? Will they access it independently from the application it references, requiring separate navigation or a search tool? And, critically, how will we manage updates and additions? Be sure to establish workflow policies from the outset of a project.

Separate Windows#section11

Popup windows have a well-deserved reputation as one of the web’s most sorely abused technologies. Conventional usability industry wisdom asserts that users want to control the experience. If they want a new browser window or tab, they’ll open one, and developers shouldn’t make the decision for them. But there are exceptions to this rule, such as links that point to non-HTML documents. When these are opened in the main browser window and rendered through a plugin, users are prone to inadvertently closing the browser instead of returning to the previous page.

Help content is another strong candidate for opening new windows, to avoid disrupting the user’s workflow. However, this practice carries some risk. Power users may be comfortable managing multiple windows, but they’re the least likely to need help. New windows can confuse less technical individuals. If the new window overlays the old one and contains the browser’s default chrome, that new window may not be obvious, and the back button will be useless to return the user to the original page.

Using JavaScript instead of a link target can help address this issue. We can control the size of a new window to ensure that it doesn’t completely obscure the original page, and we can disable the navigation bar and other chrome that isn’t relevant. But, this places a greater burden on developers to manage multiple windows well. Consider the following common scenario:

1. A new window is created with:
   
   window.open(‘widget-1-help.html’,‘help_window’,‘width=450’)
2. The user reads the content and then clicks back to the original page without closing the help window.
3. The user clicks a second help link with:
   
   window.open(‘widget-2-help.html’,‘help_window’,‘width=450’)

In many browsers (Safari being an exception), the second click will appear to do nothing at all. In reality, the new content was loaded into the existing window (because the same name was specified in the second argument to the function). But, the window doesn’t automatically gain focus when it updates. Thus each call to window.open must either specify a unique name for the window or explicitly focus it after loading.

Window management is but one of the complexities long-form help content introduces, and issues like these make a compelling argument for using embedded help whenever feasible. But even when this isn’t possible, help content links should be context-sensitive. It’s much more effective to provide links to specific topics than a general “Help” button that requires the user to re-navigate.

In the example below, Github informs a new user that he must generate SSH keys to publish code. Key generation is not a simple topic, so the site links to instructions. The link opens a separate window to a long-form help page, but beyond that, it auto-detects MacOS or Windows and displays a system-specific set of instructions—an excellent example of sensitivity to context.

Github links to instructions for creating SSH keys.

Questions and Answers#section12

Many websites structure help content in a question-and-answer format, even when they don’t explicitly use the label “FAQ.” Although the FAQ pattern has been discussed at length elsewhere, it’s interesting to consider why it works.

When written in question form, help content automatically gains a conversational, informal tone. If the user identifies with one of the questions, he feels understood—the company has anticipated his questions and doesn’t think he’s stupid. Clearly, the key here lies in writing good questions—and even if the text isn’t written as a question, informality is disarming. Help content is the last place for marketing messages. A question such as “Why are Acme widgets the very best widgets in the world?” is unlikely to help either the user or the business.

It may be challenging, however, to organize questions so that a user can easily sort through them when the writer’s phrasing doesn’t exactly match the user’s. Again, it’s helpful to link to specific topics in context rather than offer up a large pile of questions to a user who’s only asking one.

Raving fans#section13

Frustrated users can become a company’s biggest fans. People who have no trouble using a system may not give the experience a great deal of thought. But someone who has difficulty and then finds that the system anticipated their need for help (and met it effectively) is much more likely to appreciate the thoughtfulness of the system’s developers—and of the business itself. Effective help content is a powerful and underused tool to make that experience possible.