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:Indices, glossaries, etc. From:Chuck Martin <techwriter -at- VNET -dot- IBM -dot- COM> Date:Mon, 28 Mar 1994 15:26:49 PST
I was discussing the topic further with co-workers; One thing about user's
guides: they generally aren't read sequentially, where a define-in-margin
paradigm makes sense. For people who go into a book to get information,
a definition in the margin wouldn't be found in most cases, because those
definitions would appear only on first use.The only way that would
work is if the definitions appeared on each page the term was used,
which would likely cause clutter.
I like to have glossaries in my books. But then again, I like books--
I really do read the manuals, and I often read chunks of the manuals
before I even install and use my software! And I agree that the glossaries
should be referenced in the indices, but I've had books where the
glossary entry is the *only* reference from the index, which makes the
index entry singularly unhelpful.
Online help, especially those with engines like Windows Help, where
you can get pop-up definitions, does make defining terms a lot easier.
And it's no problem to have each term, or at least the first instance
of each term in a topic, one of those definitions.
Chuck Martin
InfoDev, IBM
techwriter -at- vnet -dot- ibm -dot- com
