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

[Ceri Davies]

On Sun, Apr 04, 2004 at 06:16:30PM +0200, Martin Heinen wrote:
> 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"/>

OK, that's good news.

> > > 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.

That's a valid concern that hadn't occurred to me.  Perhaps it would be
better to warn when a firstterm or acronym is missing a corresponding
glossary entry (or just do nothing?).

> 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".

That should also be possible - I'm not %100 percent on how, but I'm
confident that it wouldn't be very difficult once I get going.

Ceri
-- 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20040404/937ad79d/attachment.sig>