From owner-freebsd-doc@FreeBSD.ORG Fri Jul 9 17:10:00 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 4F9F716A4CE for ; Fri, 9 Jul 2004 17:10:00 +0000 (GMT) Received: from shrike.submonkey.net (cpc2-cdif3-6-0-cust204.cdif.cable.ntl.com [81.103.67.204]) by mx1.FreeBSD.org (Postfix) with ESMTP id B818E43D39 for ; Fri, 9 Jul 2004 17:09:59 +0000 (GMT) (envelope-from setantae@submonkey.net) Received: from setantae by shrike.submonkey.net with local (Exim 4.34; FreeBSD) id 1Biysm-000MSI-HA; Fri, 09 Jul 2004 18:09:56 +0100 Date: Fri, 9 Jul 2004 18:09:56 +0100 From: Ceri Davies To: Bill Moran Message-ID: <20040709170956.GC29928@submonkey.net> Mail-Followup-To: Ceri Davies , Bill Moran , zettel@acm.org, freebsd-doc@freebsd.org References: <200407091038.52304.zettel@acm.org> <20040709160642.GB29928@submonkey.net> <20040709125207.66591fc2.wmoran@potentialtech.com> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="ZjLa2K+dB9SFbrgo" Content-Disposition: inline In-Reply-To: <20040709125207.66591fc2.wmoran@potentialtech.com> X-PGP: finger ceri@FreeBSD.org User-Agent: Mutt/1.5.6i Sender: Ceri Davies 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 17:10:00 -0000 --ZjLa2K+dB9SFbrgo Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Jul 09, 2004 at 12:52:07PM -0400, Bill Moran wrote: > Ceri Davies wrote: > > On Fri, Jul 09, 2004 at 10:38:52AM -0400, Leonard Zettel wrote: > >=20 > > > 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. > > >=20 > > > 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. > >=20 > > 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. >=20 > I was going to _try_ to spend some time contributing to this over > the weekend. >=20 > 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? Originally I had intended for this to be FreeBSD specific - I'm now of the opinion that this is kind of unworkable and a bit pointless to boot. The main things to focus on would be things that crop up a lot, and stuff marked up in firstterm or acronym elements. Ceri --=20 It is not tinfoil, it is my new skin. I am a robot. --ZjLa2K+dB9SFbrgo Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.4 (FreeBSD) iD8DBQFA7tFkocfcwTS3JF8RAiXVAJ4sP0gLuaRTtOBlSTfNcC5mg9gx1ACcDwXi Voch5kmsf9hQ9D5EgF6iRJA= =4893 -----END PGP SIGNATURE----- --ZjLa2K+dB9SFbrgo--