From owner-freebsd-doc@FreeBSD.ORG  Fri Jul  9 16:35:34 2004
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
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 E68FD16A4CE; Fri,  9 Jul 2004 16:35:34 +0000 (GMT)
Received: from rwcrmhc11.comcast.net (rwcrmhc11.comcast.net [204.127.198.35])
	by mx1.FreeBSD.org (Postfix) with ESMTP
	id B14B143D4C; Fri,  9 Jul 2004 16:35:34 +0000 (GMT)
	(envelope-from zettel@acm.org)
Received: from [192.168.0.6]
	(bgp966574bgs.derbrn01.mi.comcast.net[68.41.108.205])
	by comcast.net (rwcrmhc11) with ESMTP
	id <2004070916353301300ivu8le>; Fri, 9 Jul 2004 16:35:34 +0000
From: Leonard Zettel <zettel@acm.org>
To: Ceri Davies <ceri@FreeBSD.org>
Date: Fri, 9 Jul 2004 12:37:04 -0400
User-Agent: KMail/1.6.2
References: <200407091038.52304.zettel@acm.org>
	<20040709160642.GB29928@submonkey.net>
In-Reply-To: <20040709160642.GB29928@submonkey.net>
MIME-Version: 1.0
Content-Disposition: inline
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Message-Id: <200407091237.04562.zettel@acm.org>
cc: freebsd-doc@FreeBSD.org
Subject: Re: Acronyms believed harmful
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.1
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Fri, 09 Jul 2004 16:35:35 -0000

On Friday 09 July 2004 12:06 pm, Ceri Davies wrote:
> On Fri, Jul 09, 2004 at 10:38:52AM -0400, Leonard Zettel wrote:
> > Things like DTD are not English, they
> > are jargon! They place an unnecessary
> > burden on the reader. This burden
> > falls most heavily on newbies and
> > (I would imagine) people to whom
> > English is a second (or third or fourth)
> > language - exactly the people who
> > most need the help of clear documentation.
> >
> > At a minimum I plead for the following rule:
> > all uses of acronyms in any document
> > should include the term fully spelled out
> > at the first appearance of said acronym.
>
> Well, there's a work in progress(ish) to have the first use of an
> acronym expand to a link to it's entry in the glossary.  This can't
> happen until the glossary is full.  Help to fill it.
>
Love to! How?
  -LenZ-
> Ceri