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.
Ruth wonders: <<Does anyone have any opinions on indexing gui elements.>>
Me, not have an opinion? Surely you jest. <g> My opinion is that now that we
have "tooltips" and "what's this?" help, indexing the interface is less
necessary than it used to be, but even so, a "visual index" is a very useful
tool indeed. That's particularly true for icons, but sometimes for other
interface thingies (note the careful use of technical jargon here <g>) such
as buttons and checkboxes. To wit:
<<My group is in the middle of a debate about including each field, button,
etc. in our index. Some claim users use the index to look up fields. Others
think it buries the real information in our user guides.>>
The context-sensitive help for each dialog box or window that contains
fields, buttons, et al., should certainly mention the field names and what
they mean and how they're used. But that's the equivalent of providing only
a table of contents: it tells you what something is only if you already know
the name. An index must do something entirely different: it must tell you
where to look when you don't know the name, but instead know what you're
trying to achieve or know a synonym for the actual name.
That being the case, you should unquestionably index the important parts of
the interface. If one button is named (for example) "Configure", it should
appear in the index in a variety of guises:
- Under its actual name, so that someone who sees it in the interface can
look up what it means.
- Under "Settings", since the goal of configuration is to change the
settings.
- As a subentry under "Change" and "Modify", since the task I'm trying to do
is "change or modify" the configuration.
- Under the name of each thing the Configure button lets you configure
(e.g., "Printer, configuring").
And so on. The more time you have, the more synonyms and approaches to
indexing you can choose.
The key here is that the ideal index (pretty much impossible to achieve in
practice, for obvious reasons) answers the question "where is this task or
item explained in the manual or help file?" for every possible question the
user could ask. A really good index probably succeeds brilliantly with the
20% of the questions users ask 90% of the time, and does an adequate job of
the other 80% of the total universe of questions.
--Geoff Hart, ghart -at- [delete]videotron -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"Wisdom is one of the few things that look bigger the further away it
is."--Terry Pratchett
RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for
competitive pricing or download a trial at: http://www.ehelp.com/techwr-l4
---
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.
