Help for multiple applications?

Subject: Help for multiple applications?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, David Loveless <daveloveless -at- gmail -dot- com>
Date: Fri, 14 Jul 2006 12:39:17 -0400

David Loveless reports: <<We produce a suite of basically 5 major applications that more or less work together. Two of these products are bundled together roughly 95% of the time. The other three products can function independently or inconjunction with the other products, and they are sold as independent products or part of a package that includes three, four, or all five of the other products... Because all five products are related in at least some way and because a help topic for one product is more than likely relevant to at least one other product, we would like to create a universal Help system that covers all five products.>>

Sounds good so far. The key thing to remember in such a system is that users will curse your name if you forget to clearly state what products each topic applies to, and what to do if someone needs to accomplish something for which they have not purchased the product. That's tricky, because "if you'd only bought product 5, you could do this" information is unlikely to pacify someone whose boss wants them to do that task _now_. So wherever possible, provide workarounds.

<<We also intend on developing this help as a web-based system so that it is more easily updated and maintained.>>

If you do that, make sure that a local version of the help is available. There's just about nothing more annoying than finding yourself desperately needing access to the help system, only to find out that the IT staff have "temporarily" disabled the network Web connection for the next three weeks while they fix the problems introduced in last week's upgrade.

<<We do use an automatic update feature with our products, but only about 40% of our users currently run the update often enough to be of any real value.>>

Um... if it's automatic, why do the users have to run it? If updating it regularly is important, make this truly automatic and take the users out of the loop. That can be tricky to implement, what with firewalls, slow dailup connections, etc., so an alternative would be to include a link to your Web site for each topic: "Did this topic solve your problem? If not, click here to see if a more recent version of this topic exists."

<<However, because some of these applications are sold as independent products, we also intend on using Conditional tags to allow access to only relevant Help files for that application.>>

I've got serious reservations about this approach. It makes good theoretical sense, but it can be appallingly complex to resolve all the dependencies. For example, where products share a help topic, there will be cross-references to that topic scattered throughout the help system. How can you tell that these cross-references will be valid for all products? The link-checking tool in your authoring software will help, but it's still going to take considerable human supervision: you have to check the links for each of five possible builds of the help system, and that's no picnic.

My take on this: provide all the topics in a single file. People who don't have a particular product are unlikely to ever see the help topics that only apply to that product, and people who do stumble across such topics will see your note "this only works if you have produce X; if you have Y, here's how you can fake it".

<<Later, we would like to add some Wiki functionality to the entire Help system to allow users to post their own information for general use.>>

This is another one of those things that sounds fine in theory, but that can be an administrative (and possibly legal) nightmare in practice. If nobody vets the information that is posted in the wiki, the resource will gradually build up a large volume of well-intentioned but misleading or outright dangerous suggestions. Someone has to take responsibility for removing this information from the wiki. In addition, if someone acts on dangerous information that seems to be recommended by your company (i.e., because it's in your wiki), all the disclaimers in the world probably won't save you in the ensuing lawsuit.

You'll also have to clearly indicate that anyone who posts information in this forum must agree to transfer copyright (at least "one-time online rights") to you. This is probably implicit in the aspects of copyright law that govern discussion in public forums, but it would be wise to make it explicit.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Help for multiple applications: From: David Loveless

Previous by Author: Good Technical writing course?
Next by Author: Plural form of 'equipment' ?
Previous by Thread: Help for multiple applications
Next by Thread: Re: Help for multiple applications?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads