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.
Subject:Renamable Terms From:Bonni Graham <bonnig -at- IX -dot- NETCOM -dot- COM> Date:Fri, 6 Jan 1995 10:42:08 -0800
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. In
my previous experience, the only things that could be customized were
field names on data entry screens, and we recommended that they keep a
table of the changes posted somewhere. This solved the paper doc
problem, and there was no online help.
I'm not so worried about the paper manual -- I think reasonable users
will realize that the paper doc is not going to change magically to
reflect their custom names. Unreasonable users are their own punishment
(after all, they have to be themselves for the rest of their lives, no?)
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.
I'm indexing and keywording the most common item alternates (we have a
list of industry regulars) so there are entry points, even though the
information itself will bear the default names.
In your experience, do users understand that the help text is not going
to reflect any custom changes? (Please note: I'm not sure that the
person who customized the names is ever going to be the only person
touching the program, so I can't count on the user just remembering that
her or she just changed the name.) If not, what methods have you used to
ameliorate the problem? I was planning on setting customizable names in
a different type (probably bold italic, or something) and then noting
the convention in Conventions at the front of the book.
Thanks in advance for the helpful replies I just KNOW I'm going to get!
Owner, Manual Labour
bonnig -at- ix -dot- netcom -dot- com