From owner-freebsd-doc@FreeBSD.ORG Fri Jul 9 16:52:09 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 6235E16A4CE; Fri, 9 Jul 2004 16:52:09 +0000 (GMT) Received: from internet.potentialtech.com (h-66-167-251-6.phlapafg.covad.net [66.167.251.6]) by mx1.FreeBSD.org (Postfix) with ESMTP id 2AD6543D2D; Fri, 9 Jul 2004 16:52:09 +0000 (GMT) (envelope-from wmoran@potentialtech.com) Received: from working.potentialtech.com (pa-plum-cmts1e-68-68-113-64.pittpa.adelphia.net [68.68.113.64]) by internet.potentialtech.com (Postfix) with ESMTP id 591FF69A39; Fri, 9 Jul 2004 12:52:08 -0400 (EDT) Date: Fri, 9 Jul 2004 12:52:07 -0400 From: Bill Moran To: Ceri Davies Message-Id: <20040709125207.66591fc2.wmoran@potentialtech.com> In-Reply-To: <20040709160642.GB29928@submonkey.net> References: <200407091038.52304.zettel@acm.org> <20040709160642.GB29928@submonkey.net> Organization: Potential Technologies X-Mailer: Sylpheed version 0.9.12 (GTK+ 1.2.10; i386-portbld-freebsd4.9) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 09 Jul 2004 16:52:09 -0000 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. I was going to _try_ to spend some time contributing to this over the weekend. Before I start, I have a policy question: If we look at tech terms that are NOT FreeBSD-specific (such as DTD) should the FreeBSD glossary contain a full definition, or possibly a link to another source? -- Bill Moran Potential Technologies http://www.potentialtech.com