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:Re: Indexing style refs From:amdohlman -at- uwalumni -dot- com To:techwr-l -at- lists -dot- raycomm -dot- com Date:Thu, 7 Aug 2003 07:29:37 -0600
>> In a modern world...what is the advantage of having "Instrument
>> container, see toolbox" references, other than teaching readers that
>> "Instrument container" and "toolbox" are synonyms?
>> True, they've learned a new synonym, but then they have to look up
>> the information twice--is that good?
Thank you for this, Mandy, as it's exactly what I was thinking. If our
goal is to make documentation as simple for the user as possible, does
the "see other" practice circumvent that? We're trained to get users
information now now now - they're busy, they're frustrated, they want to
get the answer as quickly as possible without wading through extra info
they don't need. And we try to deliver documentation that meets those
needs. Are users going to learn from the synonym, or just be frustrated
that they have to turn to another page?
My own experience tells me that this practice just frustrates me - when
I see a "see other" reference, I sigh, flip to the appropriate section
in the alphabet, locate the other "preferred" term, then flip to the page,
all the while thinking, "if they were already taking the time to create
the "see" reference, why couldn't they have just placed the page number
David Brown responded:
>> Only the first time, and that's the point of using cross-references
>> to teach vocabulary. Once readers know the preferred term, they look
>> for that (rather than their own term) on future visits to the index.
>> Also, when they see referrences to a toolbox in the text, they know
>> what it's about.
Is this really the case? How many reference books do each of us have on
our desks, and how often do we consult them? Do users really remember
the preferred term? Or is it something that resides in their short-term
memory only long enough to solve the problem, after which they forget it -
meaning that next time they need to look up the same information, they've
got to go through this "education" process all over again. For example, I
often forget how to type special characters (em and en dashes,
hyphens, etc) in FrameMaker. So I look it up. I never remember how Frame
refers to these characters or what I term I should search for, but I
remember how frustrating it is to find the information I need in their
unhelpful help. Does this practice engender similar feelings in our users?
In addition, I often use this practice while indexing:
account codes x-xx
I do this in the hope that users will only have to look up the information
once, and I'm not sure where they'll be looking. Would adding "see"
references everywhere make this more cumbersome or more useful to users?
One last point (whew!) - why teach users preferred terms in indexes? Why
won't they learn these terms from the text, when they locate the
information? If users are able to quickly locate what they need in the
index and turn to the appropriate page, won't they then learn the
preferred term as they scan through the passage?
I guess I'd rather my indexes serve the needs of the harried, "I need this
now" user, where there's several ways to get to a single page without
references. I do use them, sure, but not often. What do you think? What
your practices, and why?