Re: glossary started

[skud netizen com au]

I'll definitely take a look at it tonight.

However, one quick thing... when writing a glossary, it's important to
make sure that the definitions are in a similar style.  I'd recommend
creating a sample word/definition for people to use as reference, and
write a bit of a blurb describing how it should be done.

Remember that you have the following types of definitions:

apple: 
  an apple is a red or green fruit which grows on trees

apple: 
  a red or green fruit which grows on trees

apple: 
  one a day keeps the doctor away; the forbidden fruit of eden....

The first issue is to decide whether to include the word itself in the
description.  I'd recommend *not* doing this ... dictionaries don't, and
that's what people are most used to.  So scrap the first example above.

The second issue is whether to stick to straight facts or whether to go
off on interesting tangents.  I'd say stick to facts.  So for instance,
a definition of "world wide web" might say "An interconnected network of
documents and other informational resources available over the Internet
via the Hypertext Transfer Protocol (HTTP)", while avoiding mentioning 
Tim Berners-Lee, CERN, javascript, and whatnot.  Scrap the third example
above.

Lastly, consider the "see also" links.  How many are useful?  I'd say
that any more than 3 "see also" links are too many for most words,
though I suppose linking to documentation is a bit different to linking
to other word definitions in the glossary.

K.







-- 
Kirrily Robert -- <skud@netizen.com.au> -- http://netizen.com.au/
Internet and Open Source Development, Consulting and Training
Level 13, 500 Collins St, Melbourne VIC 3000
Phone: +61 3 9614 0949  Fax +61 3 9614 0948