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.
That's not true at all...those people who will use an index are not people
who will necessarily read the whole document (that is, after all, the whole
reason that the index exists, and savvy readers know this).
My point is that if you define the term at the beginning of the narrative,
then the whole put it in the glossary and index the glossary becomes
moot....
My reasoning is thus:
1. If that reader is like me and everyone else I know, s/he will go through
the page references, find the entries that span multiple pages, and go there
to see if it is what s/he needs (usually the discussion of the topic). If
the definition is on that page, the event ends.
<rant>
I get aggravated with entries that only include the first page, forcing me
to look at each to whittle down to the actual discussion of that topic.
</rant>
2. Single page references are used only as a last resort, and most index
page references in page order. Since the glossary generally occurs *at the
end* of the manual, that reference will be the last one, and will generally
not be tried until the end. The reader has more than likely already found
the definition, or gotten frustrated and quit (if the entries are lengthy).
Now, if you're ordering your index references carefully, and include
sub-entries, then this shouldn't be an issue. That takes a lot of work,
though.
I'm not arguing one way or another. I think it is a good idea to include a
reference to the glossary entry. However, I also think it is a better idea
to ensure that all terms are clearly defined in the text and make sure that
is referenced in the text.
----- Original Message -----
From: "Kat Nagel, MasterWork Consulting" <mlists -at- masterworkconsulting -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Thursday, April 03, 2003 12:14 PM
Subject: Re: Quick and Easy Poll
>
> >Wouldn't that be a non-issue *if* you included a clear definition of
> >the term on the first page of the discussion, before the narratives?
> >
> >Jeff Hanvey
>
>
> Sure, if you know that all your users will read the manual like a
> novel from front to back. These days, with so much to do and so
> little time, I think it's more likely that a user will want a
> specific bit of information *right now* and become irritated, like my
> client's VP, at any delay. Providing a glossary in printed material
> and including the terms in the index seems like a simple way to cover
> all bases...erm...user types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Purchase RoboHelp X3 in April and receive a $100 mail-in
rebate, plus FREE RoboScreenCapture and WebHelp Merge Module.
Order here: http://www.ehelp.com/techwr-l
Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....
---
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.
