Specifically, I mean "Help" files--the documentation that tells you how to use a bit of software. (Or at least that was the general idea before considerations of budget came into the picture. Or, worse, the Marketing and/or Legal Departments put on editorial airs.)
Being a recovering Tech. Writer, I have some strong--and, doubtless, heavily biased--views on that subject. Those will be aired in later installments.
But for the time being, I want to ensure that software or other widget-making folks understand that there are two basic flavors of "Help," and they are pretty much mutually exclusive:
- Concept-based, which is rather encyclopedic in nature. For instance, concept-based documentation will talk about the basic parts and/or functions of a widget.
- Process-based, which is a series of step-by-step instructions for performing specific tasks with the widget.
There are trade-offs between the two approaches, some of which are:
- Concept-based Help is (or at least can be) comprehensive, but it can try the patience of the person who is just trying to accomplish something with your widget.
- Process-based Help requires you (and your writers) to have some idea of what those who buy your product actually want to accomplish with it.
- Chances are good that your engineers/designers/programmers will be more forthcoming with concept-based information than process-based information. However, what goes on under the proverbial hood may be completely extraneous for your customer.
- To write process-based Help, the writer must be comfortable enough using the widget to invent those scenarios. This takes familiarity with the product, which in turn takes time.
The best of all widgets will have both sets of Help available, with the content weighted toward the process, supplemented by the concepts (e.g. in Appendix form) and hyperlinked within the step-by-step information as needed. That's a significant investment in usability.
But, as much as I would argue for making that investment, I would argue as forcefully for skipping the process entirely if you can't budget for doing it well. Simply put, no information is better than bad information.
Seriously. You, the maker, are the ultimate authority on the product. No excuses. If your Help is unintelligible, incomplete, obsolete, or just plain wrong, you're going to waste more of my time than if I had to Google everything. And if your corner-cutting is tripping me up when I need you most, well, that doesn't exactly inspire confidence in the product itself, now does it?
If, on the other hand, I know before downloading/buying that I'll have to Google my way to anything I need, that's just truth in advertising, IMO. So either fire your tech. writers or give them all the resources they need to make you shine. Otherwise, your "Help" will fall into one of the two categories defined by Shel Silverstein in the poem "Agatha Fry":
And some kind of help is the kind of help
That helpin's all about.
And some kind of help is the kind of help
We all can do without.
