Glossary [was: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide]

[Martin Heinen]

On Sun, Apr 04, 2004 at 03:44:14PM +0200, Simon L. Nielsen wrote:
> On 2004.04.02 02:27:26 +0100, Ceri Davies wrote:
> 
> > Regarding the glossary, how does everyone think that's working out?  I
> > notice that it's been short of attention recently and wanted to check
> > that people still think it's a nice idea before I do some work on it.
> 
> Even though it hasn't been getting much attention I still think it's a
> very good idea.

<aol text="me too"/>

> > My current thinking at the moment is to do away with the
> > FreeBSD-specific aspect and make it more general, then fiddle the
> 
> You mean make it both FreeBSD and general?  That would probably be a
> good idea, and also give the glosserary a better reason for for existing
> if it has more actual content.
> 
> > stylesheets to create links to the glossary term for firstterm and
> > acronym elements
> 
> That sounds like a real neat idea.  Acronyms can appear many times on
> one page, so perhaps only the first occurrence on a page should be
> marked up with a link.  Eg. like only the first occurrence a trademark
> on a page gets the trademark symbol.

Linking to the glossary might be a bad idea.  As with
footnotes, linking will distract the reader.  New items
should be explained on the first occurrence; I fear that
adding links will move the definition of important terms
solely to the glossary.

The glossary should enable the reader to look up important
terms without having to read a whole chapter.  When I start
to read a book, I will skim over the glossary first.
While reading the book, I tend to ignore the glossary,
but often return to it afterwards.

The glossary should point the reader to relevant
chapters of the Handbook.  For example, when
explaining ports, the glossary could link back
to the chapter "Packages and Ports".

Compare reading wikipedia.org to reading the
Handbook.  When reading the Handbook, I expect
to get information in a serial manner.  Browsing
the glossary would be comparable to wikipedia.org,
where following links is expected.

-- 
Marxpitn