Good Help is Hard to Find
Issue № 312

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.

Article Continues Below

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.


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:

If you did not receive a confirmation e-mail, check your spam filter. Your e-mail program may have misidentified the confirmation as spam. If you still can’t find it, see the topic “You did not receive an expected e-mail.”

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:

If you haven’t already, check to see if our message landed in your spam folder. If it’s not there, give us a call and we’ll be happy to help you activate your account.

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.


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.


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

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.


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

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

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:‘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:‘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 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

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.

22 Reader Comments

  1. I think that popups are not useful at all. Instead, you can use modal dialogs or normal links to help pages (if there’s too much text).

    Good note about marketing messages in FAQs! I hate when they do so.

  2. Overall this was a very good read, I especially like the portions on tone and brevity.

    The only part I would disagree with is, like the previous commenter mentioned, opening content in separate windows. This may be a personal preference, as I’ve never actually heard a normal user complain about help content opening in a new window (as long as the pop up blocker doesn’t grab it). I also dislike modal windows, but that’s definitely a personal preference.

    You made some good points in that usually someone seeking help documentation is already frustrated and the importance of offering quick/easy solutions.

    Nice read, thanks.

  3. As a technical writer, I have always been trying to provide useful content in a usable way. However, I often got caught up in releases and just try to finish the release notes and new features document. (I have written 70-page-long release notes. God knows who read that. )

    It’s really hard to convince higher management that more content does not equal good content. It’s been an on going battle. The on-screen texts have not gotten attention they deserves, so… think about the behind application contents.

    One thing I’ve learned in my job is to have a content maintenance calendar. Sometimes developers change things on the fly without telling the writer or log it in the tracking system. By the time the writer finds out, it’s probably several versions back. Outdated content lose credibility.

    Your article has many valid points and thanks for writing it. And it would be great if everyone realizes the significance of help content as you do.

  4. I’ve spent the summer working on documentation, and one problem with your article is that the majority of our users reach our site through Google. People phrase their search queries as answers, not questions, so page titles that begin with a question often fail the scan test.

    One way around the problem would be to title the page as an answer, but have every link to it be in the form of a question.

  5. @kevinburke Sure, question-style organization doesn’t always fit. My point was just that this kind of writing helps to establish a sense of empathy, so even if you don’t write the items in question form, it helps to keep the style conversational.

  6. I definitely enjoyed reading the article and thought it was pretty thorough on the options of help.

    Are there any recommendations on tools or services for authoring help content (longer form)? Especially in providing a good way to contextually link to the help content generated.

    There seem to be a lot of tools focused on the customer support side, but less on the generation of great docs.

  7. Excellent article. Too many web designers see the need for online help as a failure of design. But many web apps deal with complex domains where the user does not arrive with all the necessary concepts in their head.

    @chrizbo: For Help Authoring Tools (HATs), see for a searchable database of tools that help with the mechanics of authoring and generating help content. But to get “great docs”, you need a talented technical writer who takes a user-centered approach.

  8. @chrizbo, I think @jmswisher makes a good point. The quality of content is driven far more by the writer than the tool. As far as contextual linking, this depends so much on the specifics of the application that it’s hard to generalize.

  9. This is a really nice overview of online Help and it’s really nice to see it on A List Apart!

    But I think I’ve found your controversy 😉 ( In the last paragraph of the introduction, you say: “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.”

    I know several hundred people who would argue with this, me among them. (And there are probably many thousand who I don’t know who wouldn’t agree with it, either.) Our professions include technical communicator, technical writer, online Help developer, online Help author, and more. We want to create that content. We like maintaining it. And we take pride in providing Help and user assistance that is easy to use, well written, and high quality.

    (Disclaimer: I own and, where you can find a list of tools under Authoring.)

  10. @CharJTF that statement was definitely hyperbolic, but I do think effective help is far more the exception than the rule in our industry as a whole. Kudos to those who do care about it — we need more of you.

  11. Well done article with good recent examples of successful Help applications on the Web.

    Long-time Help authors like myself are familiar with these concepts, but unfortunately, like usability testing, our budgets have been decimated, jobs shipped to India, etc. and so although we know better, we’re told to do more with less. Developers at small firms don’t know how to embed Help and don’t want us writers messing with “their” code or possibly interfering with their launch dates. So app Help remains in an HTML or PDF file and simply linked up during the setup build. They also just want “all the commands documented” and don’t really care if it’s organized properly by task and troubleshooting issue. They still want screen grabs for some crazy reason, though…which takes yet more time for what I feel is very little utility (online; it is helpful in print).

    It is nice to see how Twitter and some of the newer companies seem go “get it” and go out of their way to think through the “real” user experience. Perhaps we first-generation Help authors will live long enough yet to actually implement the ideas we’ve had all along!

  12. @mullican, Thanks! Kudos are always appreciated (personally and for the profession itself).

    Think of Help authoring on a bell curve. There’s both good and bad, with the bulk falling in the center of the bell. Then picture that bell curve running across all industries and professions, and (to me at least) it makes sense why good Help is more the exception than the rule. It’s really easy to see why more people experience poorly-written Help.

    Technical writing itself is now recognized as a profession by the US Department of Labor Bureau of Labor Statistics in the Occupational Outlook Handbook ( and the STC is working on a certification program ( Not all tech writers are Help authors, but quite a few are. These two changes alone will help improve both the quality of the output and the pay because they make tech writing a more viable profession.

    PS I once complained about T-Mobile’s documentation for the Shadow because a sample screen shot included the “TM” in a field 😉

  13. Thank you for this post! Your depth into the intricate UX mechanizations and their potential for building the *right*, per case help doc is extremely…well, helpful!

    As to your mention of the importance of practicing good curation, that couldn’t be a hotter topic right now. Forbes recently ran a HAT software solution that headlines curation and is making pretty big waves in the help authoring community. It is well worth a read for entrepreneurs, those entrenched in their business and technical communicators alike:

  14. Interesting article, and as a technical writer, these are many of the things we try and tackle as part of our remit.

    With more companies looking to ‘social media’ to help solve customer issues, it’s interesting that the very websites they are creating might not be all that ‘helpful’ themselves.

    The overlap between the various industries at play here is something I’d love to see more of – IA, web design, content management, application design, technical writing – as we can all learn from each other to make that customer experience even better.

  15. Absolutely spot on with your closing remark about raving fans. As a user of Github, I’m constantly delighted by their inline help and help pages. One of the things that makes Github so great is the fact that, although it’s a fairly complicated system, they make it so easy.

  16. This is a great article, and as such deserves one significant correction; “With modal dialogs, you can present longer or more complex content without taking a user out of the current workflow.” Eh hem. While it’s true more content can be contained, because of the captive audience a modal dialog demands, in terms of flow interruption, a modal dialog is specifically for interrupting the flow of a human-computer interaction. I just thought it should be clarified.

  17. @uxdesign-com, I think that would depend on how you define “workflow.” A modal dialog essentially freezes the state of the application or page while presenting its content. in most implementations, that page or application remains visible behind the modal window even if it’s not actionable. So yes, it creates an interruption in the sense that the user can’t complete the task without closing the dialog — but the sense of context is still strong cognitively, so I think it’s valid to consider a modal interaction as part of the overall workflow.

  18. Great read. I whole-heartedy agree with the section on “Questions and Answers”. The additional benefit of structuring your help this way is that it becomes much easier for your support agents to use the help in a support situation. A customer asks, “How do I export a document?” The agent just points them to the help page titled “How do I export a document?”

    We follow a method we call “Plan Not to Plan”: It is a very simple methodology that has worked well for us and our customers. We basically create out help content based on actual questions our customers have.

    Another way to improve help is to include _lots_ of pictures. For procedural type help this will dramatically decrease your reliance on your technical writing skills as the pictures will do most of the work.

    _Disclaimer: I develop a product, “ScreenSteps”:, that is designed to create image-based help files. So I might be a little biased :)._

  19. Glad to come across a topic aimed straight at the heart of one of my dreaded enemies…the help and support files! Don’t get me wrong, I don’t mind creating them for my client’s sites, I just procrastinate to no end when it comes to implementing them on my own.

    For what it’s worth – while I have a meager Help directory that allows clients to view slideshows. I finally broke down and created a “support” form. Currently in the process of creating a Client Portal that will allow them to not only request new services, but also review all documentation related to their account and yes, another, more in-depth, dreaded support request form.

    Thanks again for the read. Very informative.

Got something to say?

We have turned off comments, but you can see what folks had to say before we did so.

More from ALA