We’ve played around with reworking the traditional help system (and renaming it as “learning topics”) at Red Gate. Take a look at http://www.red-gate.com/supportcenter (and then pick a product to see its learning topics).
It’s well used, and mostly successful, although some tweaks are needed to the architecture. We couldn’t find anything that could enable this out of the box, though, and had to get some development work done to help build it.
I’m looking forward to see what LugIron are doing in this direction: sounds interesting.

[Reply]

Ben Reply:
August 7th, 2009 at 7:03 am

Thanks for giving an example. I’ve thought about how, if in my organization we dreamed up a certain way we wanted to do a “learning center” or some similar concept, we would probably need a dev project for it. But right now, when there’s some emphasis on making do with what you have, I expect the feedback would be that help systems, quick reference guides, and videos are sufficient, and there are higher priority projects planned.

[Reply]

I’m not stating everyone who puts their Help on the Web will have 9 times the number of users, but each company I’ve met, who has done this, is reporting comparatively huge numbers.

Why is this?

We were told that a lot of users were just so used to using Google to search that they would go there than use F1 Help,even when they were told there was F1 Help available.

The other reason we were given was that a lot of readers were not customers – they were prospective customers checking out the capabilities of the software/hardware prior to purchasing it. Help was a selling tool, in effect.

Regarding the word “Help”. Joe Welinske did a presentation a while ago about when Microsoft considered renaming Help in Windows. Help implies failure, was their reasoning. Apparently, they couldn’t come up with a better word than Help.

Ellis Pratt

[Reply]

Ben Reply:
August 7th, 2009 at 6:41 am

Ellis, thanks for offering some context. I was hoping you would. I was taking a brief statement about your “Beyond Documentation” webcast and skipping off down the path it took me.

Regarding potential customers using help to consider a purchase, I saw that a LugIron blog post and a TechCom Manager feature article are just out that talk about documentation helping profits, but I haven’t had a chance to read them yet.

[Reply]

Hmmm; maybe we could discard terminology and approaches that are common to (my WAG) 95% of applications out there and weld on a confusing new interface with hitherto unused terms, discard a couple decades of user experience and proclaim it wonderful. Let’s call it the Ribbon.

[Reply]

Ben Reply:
August 7th, 2009 at 6:49 am

You have a way of making a point. Though for many people, Microsoft was fixing something that wasn’t broken when they came up with the Ribbon. Help (of the traditional, “F1″ variety) has the reputation of being rarely accessed, and in spite of this, it hasn’t changed much in years. To me, the traditional help format has become somewhat stale. It doesn’t match the way that people like to get assistance.

As for renaming it, I have noticed that some software, MS Office included, just uses an icon now and doesn’t use the word “Help” in the interface. Sometimes people get too focused on words, but words do color perceptions. If “Help” has negative connotations for 75% of the population (one of those made-up-on-the-spot statistics), then most of that 75% will never click that link or icon or press F1.

[Reply]

I tried to post this as a reply but think WordPress decided it was an invalid post…

Oddly enough, the topic came up in the MS Office 2007 Yahoo group digest email I received this morning:

http://www.writestarr.com/MSO2007-Help.txt

(I edited it to remove real names and email addresses).

[Reply]

I people aren’t accessing help, redesigning its format isn’t going to get them to use something they’re already not using. Making it a little bit more self-evident might make a difference… “Press F1 for user manual/help.”

However I think the main reason help isn’t being used is because what they’ve gotten in the past was so dismal. It was dismal because many technical writers decided that it was only necessary to create online help that addressed a modest subset of user tasks and to completely omit any reference information, even for applications that have enormous power and flexibility. The help would contain instructions for a basic task that uses a dialog box that has perhaps 20 controls and that basic task would use at best four controls on the dialog box. There would be no way of finding out how the other 16 controls on the dialog box impacted the results.

Or, if there was something that addressed additional controls, it would be something like: “You can adjust the gamma for the image with the Gamma control.” and no explanation of what adjusting gamma really means/does.

The online help also frequently failed from an indexing standpoint. If the help had any indexing at all, it didn’t contain terms that the customer could identify as what they were looking for.

Is it any wonder they stopped trying the F1 help and resorted to Google where they might eventually find a link to a topic in the product’s support forum that actually explained things? However, using the Google approach takes up way more time than desirable.

Left to my own devices, every user manual and help file I create (and I usually use some mechanism for single-sourcing) will contain the same content:

Introduction
Common procedures
Reference section including descriptions of each element of the user interface (menus, toolbars and every dialog box).
Index

When the online help file is complete, I have all I need for context-sensitive help for every dialog box.

And yes, I’m going against the grain here… current received wisdom says online help should be procedural only but I reject that in favor of online help and user manual containing complete documentation. My theory is that users will look in their preferred form of documentation for an answer and if they don’t get what they’re looking for in that form, they’ll pick up the phone and call tech support rather than looking in other forms.

Given that the norm is now to avoid printed documentation, there’s no longer any need to limit the length of documentation. The extra bytes required for complete documentation don’t add to the distribution cost. IMNSHO, saying too much documentation is a bad thing is BS. It’s a bad thing if it’s poorly structured and indexed but it’s a wonderful thing if it’s done right.

[Reply]

Ben Reply:
August 7th, 2009 at 5:31 pm

Very interesting email thread. Thanks for posting that. (You’re right, Akismet thought it was spam when you posted it directly in the comment. Not sure why.)

I agree with you about including both tasks and reference information in documentation. I don’t buy into the idea that it should be all tasks, nothing else.

And most of us are struggling to overcome that bad experience that the users had with the dismal help. I think part of that problem has been the practice of having developers or project managers taking on the writing themselves.

[Reply]

Why try to change user behavior when they seem to like doing things a certain way? Isn’t that basic usability that we tell the product teams – find out how users want to do things and design to make that easy?

I’d say that in addition to having your Help in the product, put it on the Web and make sure it’s easy to find through Google and Bing. As Mike Starr wrote, people look where they feel comfortable looking.

[Reply]

Ben Reply:
August 7th, 2009 at 5:34 pm

I don’t think it’s a matter of changing user behavior; rather, it’s trying to give them something that matches their current behavior—as you said, usability. The point that you and Mike made together, though, suggests the need for multiple forms of documentation. Not everyone looks for assistance in the same way, so multiple formats will benefit more people.

Sometimes I talk from the standpoint of working on internal projects that won’t be on the Web, so the documentation shouldn’t be there, either. Perhaps that’s a better case for making help look more like a website.

[Reply]

We’ve been putting Help documentation for internal tools on intranet-only wikis for a couple of years now. That probably wouldn’t work for everybody, but it would seem strange to have static compiled Help files for our tools.

Thinking a little more about it, it might work so well because all the users are pretty technical. We don’t look for Help about how to use dialogs and wizards, since those are usually based on models we’re familiar with from other programs and we can figure them out. We look for Help about what process we should be following to do specific tasks – WHICH fields to fill in for a type of file, instead of how to fill in fields generally. Only the teams using the software know those answers.

[Reply]

I would love to put help content on the web, but due to its confidential nature, it can only appear on the intranet. Unfortunately, our intranet lacks a robust search at the moment. So users are kind of forced to use the help button in the application.

Re embedding the search field in the topic, I queried the Madcap forums for info how to do this in Flare, and Dave Lee posted a solution.

[Reply]