Comments on Good Help is Hard to Find

22 Reader Comments

Back to the Article
  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.

    Copy & paste the code below to embed this comment.
  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.

    Copy & paste the code below to embed this comment.
  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.

    Copy & paste the code below to embed this comment.
  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.

    Copy & paste the code below to embed this comment.
  5. “Charbeat” should be “Chartbeat”

    Copy & paste the code below to embed this comment.
  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.

    Copy & paste the code below to embed this comment.
  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.

    Copy & paste the code below to embed this comment.
  8. 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.)

    Copy & paste the code below to embed this comment.
  9. 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!

    Copy & paste the code below to embed this comment.
  10. @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 ;-)

    Copy & paste the code below to embed this comment.
  11. 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:

    Copy & paste the code below to embed this comment.
  12. meant to say Forbes recently ran “an article about a HAT software solution”...

    Copy & paste the code below to embed this comment.
  13. 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.

    Copy & paste the code below to embed this comment.
  14. 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.

    Copy & paste the code below to embed this comment.
  15. 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.

    Copy & paste the code below to embed this comment.
  16. 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 :)._

    Copy & paste the code below to embed this comment.
  17. 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.

    Copy & paste the code below to embed this comment.
  18. Sorry, commenting is closed on this article.