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.
When indexing interface elements in manuals (administration or installation
guides), we currently format entries in bold, and include only the actual
name of the element in the entry. For example, the index entry for the
configuration setting Default PIN looks like this:
<B>Default PIN
I'm wondering, however, if it would be better to specify what the element
is. Is it a checkbox, setting, tab, window or even a report? This wasn't
really an issue in the past because not that many interface elements were
indexed, but as our product matures and new features are introduced or old
ones change names, we're finding it necessary to include more of them in
the index. Since there will be more interface elements in the index, we're
wondering whether it makes since to include the type of element in the
entry, so it would like this:
<B>Default PIN</B> configuration setting
or
<B>Can be used as template</B> checkbox
This would also accomodate readers who are staring at a new element on the
interface and quickly want to know what it does without knowing the heading
under which it would appear in the index (or so we think. Since I'm looking
for feedback here, feel free to tell me otherwise).
What do you think of this? Should "configuration setting" appear at all,
and if so in brackets?
We use CMS for our index currently, but it isn't really geared to tech.
publications.
What do you think?
Johanne Cadorette
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Save $600: Create great-looking Help files and software demos with
RoboHelp Deluxe. Get RoboHelp and RoboDemo - our new demo software - for one
low price. OR Save $100 on RoboHelp Office in June with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
