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.
> I'm currently documenting a product for a client. This product includes
> item names that can be changed to reflect the users' needs. The new
> name appears in printed information, and on all the program's title bars
> and dialog boxes. Unfortunately, this means that the only items not
> reflecting the custom name are the paper manual & the online help.
...
>What I'm concerned about is the online help, since it always appears to
> be much more of a part of the *program*. My client is worried that
> users will expect to see their changes automatically reflected in the
> help. I'm not so concerned -- I don't think they will, but I don't
> want to bet my record for excellence on that assumption.
> In your experience, do users understand that the help text is not going
> to reflect any custom changes?
Although it is hard to say without seeing the program, I'd have to say that,
unless the end users understand from the start that their version of the program
has been customized (and hence, that some names will be different on the
help screens than on theirs), your client is probably correct that the users
will find the difference troubling.
However, expecting to see their changes magically reflected in the help
is unrealistic. (Of course, most people, computer savvy or not, do believe
in magic, so telling them how unrealistic their expectations are doesn't
necessairily help.)
Unless, of course, you can provide them with a way to actually incorporate
those local customizations into the help system. I had an idea that since
you probably know what is going to be customized, you might be able to
do that. Here's my thought.
Provide your clients with the source RTF files for the help system as well
as copies of the help compiler. (Licensing might or might not be an issue
there. I think the compiler can be downloaded free from CompuServe et al
so you could always give them directions on where to find it.) Where resources
will have customizable names, you don't use the standard, or default, name. You
use a variable. For example, in place of the title bar name for my email screen,
I might put "&tb-email-mainscrn;" Not likely to be a regular part of the text
anywhere else and easy to identify.
Then you have somebody in your company build a little utility front end where
they get the name of the resource (Email main screen title bar) and the
default name in a box that they can replace with the customized version.
When they have finished filling out all the customizations, they click the
"Process"
button (or something like that) and it a) replaces all those variables in the
RTF, then invokes the help compiler to produce the customized, localized
help system.
I have *Absolutely No Idea* how much it would take to develop this. And there
are probably a whole attic full of legal issues attached to the proposal of
turning over the source code for the help system to your customer. However,
it sure could be done, and if tied directly in to whatever system they use
to localize the software itself, could be kinda neat.
Hope this helps.
/chet
---
Chet Ensign
Director, Electronic Publishing
Logical Design Solutions, Inc.
Phone: 908-771-9221
Email: chet -at- lds -dot- com
Email (home): censign -at- interserv -dot- com
The opinions expressed here are solely my own and do not express the opinions
or policies of Logical Design Solutions.
---
