Comments on: Paving the Road to a User Utopia

By: Paul Sholar

Paul Sholar — Sun, 31 May 2009 23:52:16 +0000

Eddie, I think that the task of shepherding the user to greater expertise in using the product should be the *product’s* responsibility, not the documentation’s. The documentation has to do that job nowadays because today’s UI frameworks aren’t yet up to that task. If the product itself kept track of the user’s competence level and also knew more explicitly what the user is trying to accomplish, then supplying the user with the proper assistance for the task at hand would be a lot more feasible. But the UIs today aren’t designed to be intelligent about those kinds of things, maybe someday. So we TCers have user shepherding to do in the meantime.

By: Eddie

Eddie — Sun, 31 May 2009 23:40:58 +0000

Paul, thank you for your contribution to this discussion. I agree that verbiage is secondary to the organization of the content. I only included it because (1) I’m habitually attuned to it; (2) I believe that we can improve it; and (3) I have worked with groups whose audiences often commented on the language factor. (I recall seeing the word “drudgery” in the comments.)

I really appreciate your second point. My ideal is an intuitive application with documentation that simply gives usage scenarios to take users to the next level. Thus the word “utopia” in the title.

By: Paul Sholar

Paul Sholar — Sun, 31 May 2009 22:00:03 +0000

1. I think the “tone” or “style” of documentation’s verbiage is a lot less important than the number and organization of facts found in the content. The content’s explicit structure and visual cues must reinforce to the reader what kind of content is being presented.

2. The more robust (feature-rich) is the product, the more the documentation’s design and presentation should allow for an evolution of the user’s expertise in using the product. Of course, the product itself (interactive ones, anyway; an API ain’t going to adjust itself to the user’s expertise) should allow for this as well.

By: Eddie

Eddie — Sun, 31 May 2009 21:58:46 +0000

Tom, thanks for your comments, and thanks also for the compliment on my site.

I guess I have to answer your question with a question: How giant is “giant”? What I’m suggesting is a portal page that lists and describes various user roles and the typical tasks that each user performs. The role name could link to a subset of information targeted only to the selected role. This type of selection process may not work for you if the role groups in your organization aren’t significantly large. This was just on my mind because a few of my clients are managing this process using merged help files and including/excluding subsets with conditional text and other methods.

It’s interesting that you mention the TechSmith product help, because as I have learned my way around SnagIt 9, I have found the help a bit frustrating. But TechSmith does provide some great supplemental help through the forum, and I like their videos, too.

By: Tom Johnson

Tom Johnson — Sun, 31 May 2009 21:22:03 +0000

You’re responding to an interesting situation, one that I’m currently facing. Given that we adopt best practices for making the information findable, searchable, readable, etc., is it then okay to deliver a giant help file with all scenarios described and explained?

At the last Summit, I asked the Techsmith people why their help files were so sparse, yet their support forums dense. It seems like they skimped on some information that should have been included in the help file. Their response was that overloading the help file increased the cost of translation. Weighing the cost of translation doesn’t really make a big difference in how I write my documentation, but it is another dimension to the problem of how much documentation to deliver.

By the way, I like your site’s style. You’ve done a nice job making it very readable.