From owner-freebsd-doc@FreeBSD.ORG Wed Jul 14 13:08:00 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 815) id 0258116A4CF; Wed, 14 Jul 2004 13:08:00 +0000 (GMT) Date: Wed, 14 Jul 2004 13:07:59 +0000 From: Murray Stokely To: Warren Block Message-ID: <20040714130759.GD66732@hub.freebsd.org> References: <20040712171533.R43767@wonkity.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20040712171533.R43767@wonkity.com> User-Agent: Mutt/1.4.1i X-GPG-Key-ID: 1024D/0E451F7D X-GPG-Key-Fingerprint: E2CA 411D DD44 53FD BB4B 3CB5 B4D7 10A2 0E45 1F7D cc: doc@freebsd.org Subject: Re: Handbook Acronyms X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 14 Jul 2004 13:08:00 -0000 On Mon, Jul 12, 2004 at 05:31:25PM -0600, Warren Block wrote: > In most books, the first use of an acronym or term is defined. With the > Handbook, that is probably not very helpful, since most users will not > read it straight through and may miss the definition. > > A glossary would help, particularly for HTML, where the definition is > just a link away. This fails on paper versions of the Handbook, though. > > Ideally, the first use of a glossary term in a chapter would have a > short definition: > > With NFS (Network File System), files may be... This reads better as 'With the Network File System (NFS), files may be...' rather than having the expanded form in parenthesis, but otherwise I agree with your main point of avoiding undefined acronym-overload. - Murray