[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

Re: Glossary structure

Subject: Re: Glossary structure
From: Sandy Harris <sandy -at- storm -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 08 Sep 2004 15:14:39 -0700


David Tinsley wrote:

I would like to solicit opinions on glossaries, We have recently
consolidated our glossary terms from long explanations to one or two
sentence definitions. Our rationale is that we believe that the subject
should be discussed in detail at the appropriate place in the text.

Yes, if it is in your scope. In that case, your glossary
should link to the longer explanation in the main text.

What if it is out of your scope, a term you need to use
that is not particularly specific to your product? I'd
say in that case, give an external link for anyone who
needs it.

We had
instances where the glossary was as large as the main text!

Here's a glossary I wrote that was the largest single
file in the doc set:
http://www.freeswan.org/freeswan_trees/freeswan-1.98b/doc/glossary.html

To really understand all aspects of that product you'd
need to be expert in at least three things:

Linux system administration
TCP/IP networking
cryptography

Almost no-one is actually good at all those, but most
readers would be moderately familar with one or two.

I wrote the main text assuming reasonable familiarity
with all of them, but with lots of links -- glossary,
bibliography, web links file -- for background.

I suspect many products are a bit like that. You cannot
be cetain what users will know, so you need a lot of
supporting material beyond what a mythical perfect user
might require


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
Glossary structure: From: David Tinsley

Previous by Author: Re: Asking for Author Credit In The Documentation?
Next by Author: Re: Interoffice Relations/Work Productivity Dilemma
Previous by Thread: Glossary structure?
Next by Thread: RE: Glossary structure

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

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

Sponsored Ads