Creating content for a glossary

Subject: Creating content for a glossary
From: "angela pollak" <angela -dot- pollak -at- sybase -dot- com>
To: techwr-l
Date: Thu, 13 Apr 2000 16:28:14 -0400

As part of a mandate to create a house writing style and make our manuals
more consistent, I've been charged with the responsibility of updating our
glossary. (We document RDBMS software across seven manuals, nearly 1 000 000
000 words total. Very little GUI, highly technical. But that's another day
on the riverbank...)

'How hard can that be?' I thought naively, only several weeks ago. 'I know
what a glossary is. I know how to use one. Update ours? No sweat.'

Ha!

Now, several weeks into the project, I find myself the cause of great
dissention (or at least intense discussion) among the ranks about exactly
what the role, purpose and content of a glossary - and ours in particular -
should be. Frankly, we've all got different ideas, and progress has all but
ceased. Glossaries aren't as straightforward as I first thought.
Whoduvthunkit?

I've decided that we really need to get an outline in writing before we
proceed any further, or we'll have nothing to measure our success by, and
we'll be no further ahead when the experience is over. We all have to be
working off the same page. And so, after turning to the archives for
suggestions and ideas and coming up blank, I turn to you folks. I'd
appreciate any opinions on any/all of the following subjects (or other
glossary-related subjects if you have an urgent desire to share):

1. How do you (as a user) use the glossary of a book... (word look-up?
browsing? some other way?)

2. How do you (as a writer) determine the criteria by which words gain
admission to the glossary?

3. Some technical terms are discussed and defined in the text of the
manuals... how does this fit into the glossary issue? Should these
definitions be in both places or just one?

4. Are there any other resources I can consult on the subject?

Many thanks for your kind words.

~Angela~






Previous by Author: Re: professionalism in TW...
Next by Author: Re: Re. Documentation size & shape research?
Previous by Thread: Re: Job Selection Dilemma-Decision Made
Next by Thread: RE: Creating content for a glossary


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


Sponsored Ads