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.

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.

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.

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.

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.

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.

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).