From owner-freebsd-doc@FreeBSD.ORG Sun Apr 4 09:16:34 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 2A4B316A4CE; Sun, 4 Apr 2004 09:16:34 -0700 (PDT) Received: from Kain.sumuk.de (Kain.sumuk.de [213.221.86.114]) by mx1.FreeBSD.org (Postfix) with ESMTP id BF51B43D58; Sun, 4 Apr 2004 09:16:32 -0700 (PDT) (envelope-from vincent@sumuk.de) Received: from Goliath.earth.sol (Goliath.earth.sol [192.168.1.6]) by Kain.sumuk.de (8.12.10/8.12.10) with ESMTP id i34GGUt5019714; Sun, 4 Apr 2004 18:16:30 +0200 (CEST) (envelope-from vincent@sumuk.de) Received: from Goliath.earth.sol (localhost.earth.sol [127.0.0.1]) by Goliath.earth.sol (8.12.10/8.12.10) with ESMTP id i34GGUW3040455; Sun, 4 Apr 2004 18:16:30 +0200 (CEST) (envelope-from vincent@Goliath.earth.sol) Received: (from vincent@localhost) by Goliath.earth.sol (8.12.10/8.12.10/Submit) id i34GGUto040454; Sun, 4 Apr 2004 18:16:30 +0200 (CEST) (envelope-from vincent) Date: Sun, 4 Apr 2004 18:16:30 +0200 From: Martin Heinen To: "Simon L. Nielsen" Message-ID: <20040404161630.GB39330@sumuk.de> References: <20040404134413.GB2933@zaphod.nitro.dk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20040404134413.GB2933@zaphod.nitro.dk> User-Agent: Mutt/1.4.1i cc: Ceri Davies cc: freebsd-doc@freebsd.org Subject: Re: Glossary [was: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide] X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list Reply-To: "Simon L. Nielsen" , Ceri Davies , freebsd-doc@freebsd.org List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 04 Apr 2004 16:16:34 -0000 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. > > 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