TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
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!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
