1 Popup windows

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.

posted at 10:16 am on August 17, 2010 by scriptin

2 Overall

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.

posted at 12:44 pm on August 17, 2010 by Tim Wright

3 All Valid but Hard to Promote

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.

posted at 01:20 pm on August 17, 2010 by Yina

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.

posted at 01:56 pm on August 17, 2010 by kevinburke

6 Typo in second screenshot caption

“Charbeat” should be “Chartbeat”

posted at 05:50 pm on August 17, 2010 by fiveminuteargument

8 Good help documentation organization and authoring

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.

posted at 08:29 pm on August 17, 2010 by chrizbo

9 Lots of HATs out there

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 http://hat-matrix.com/ 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.

posted at 11:41 pm on August 17, 2010 by jmswisher