RE: About online glossaries...

Subject: RE: About online glossaries...
From: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>
To: <mbarwick -at- invatron -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 10 Apr 2008 10:30:28 -0700

I do #3 and #1 (sort of). I have each glossary entry as an individual
file tucked away in invisible topics (topics that don't appear as
stand-alone pages in the help TOC) so that I can embed links that throw
pop-ups in my help. When a reader is reading along comes across a phrase
with which he is not familiar and happens to be in the glossary, when he
hovers, the cursor becomes a question mark. When he clicks, a pop-up
appears/opens/is executed/displays with the definition of the term. I
would stop here if I were building only on-line help. However, since I
also build PDFs, I have embedded all of the individual files in a single
topic ("Glossary") that does appear in the toc.

If you wanted only a single page, you could accomplish similar
functionality by having all of the glossary entries on a single page,
each entry with its own anchor. In this construct, when the user clicks
a hyperlink to a glossary entry, he lands on the glossary page at the
given entry. The reason I didn't take this approach is that I didn't
want the user to lose his place in the workflow just because he needed
to look up a phrase.

As a final note, I use a different link style for glossary entrees than
for normal hyperlinks so that it is clear to the user when he is going
to be redirected.

L.C. Porrello

-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of mbarwick -at- invatron -dot- com
Sent: Thursday, April 10, 2008 9:55 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: About online glossaries...

Greetings, all.

I'm in a position to determine what should happen in a new online help
system and I'm curious as to what people are doing with their online
glossaries (if they even have them).

Here are three possibilities I can envision:
1) All glossary terms in one topic, which is linked to from the main
introductory topic
2) All glossary terms in one topics, which is linked to from major
or all perhaps even all topics
3) All glossary terms as separate topics with links to occurrences in
topics (perhaps to appear as pop-ups)

#3 seems the right way to go because a single glossary topic is likely
go unread. If the user can access a term's definition simply by
it seems to me it will more likely be used and frankly, it will be more
useful. The only trouble is that the task of building all those links
would be like indexing only worse, and take considerable time depending
the size of the help system. :-(

If you build online help, tell me what you're doing with your glossaries

for I would dearly love to know. Only another tech writer could be so

Best wishes,

Michael Barwick
Senior Information Developer
Invatron Systems Corp.
mbarwick -at- invatron -dot- com


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

About online glossaries...: From: mbarwick

Previous by Author: RE: How do you define your audience/"user requirements" in your docs, to the reader?
Next by Author: RE: Replacing "master" and "slave" terminology
Previous by Thread: About online glossaries...
Next by Thread: Levels of Edit

What this post helpful? Share it with friends and colleagues:

Sponsored Ads