From owner-cvs-all@FreeBSD.ORG Thu May 8 01:24:08 2003 Return-Path: Delivered-To: cvs-all@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id CB23637B404; Thu, 8 May 2003 01:24:08 -0700 (PDT) Received: from core.byshenk.net (core.byshenk.net [62.58.73.230]) by mx1.FreeBSD.org (Postfix) with ESMTP id 3532D43F3F; Thu, 8 May 2003 01:24:04 -0700 (PDT) (envelope-from byshenknet@byshenk.net) Received: from core.byshenk.net (localhost.byshenk.net [127.0.0.1]) by core.byshenk.net (8.12.6/8.12.6) with ESMTP id h488MeGv069089; Thu, 8 May 2003 10:22:40 +0200 (CEST) (envelope-from byshenknet@core.byshenk.net) Received: (from byshenknet@localhost) by core.byshenk.net (8.12.6/8.12.6/Submit) id h488Md3K069088; Thu, 8 May 2003 10:22:39 +0200 (CEST) Date: Thu, 8 May 2003 10:22:39 +0200 From: Greg Byshenk To: Wes Peters Message-ID: <20030508082239.GC64674@core.byshenk.net> References: <200305071859.44725.wes@softweyr.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <200305071859.44725.wes@softweyr.com> User-Agent: Mutt/1.4i X-Mailman-Approved-At: Thu, 08 May 2003 04:41:41 -0700 cc: Tom Rhodes cc: Doug Barton cc: cvs-all@freebsd.org cc: John Baldwin cc: Hiten Pandya cc: David Schultz cc: doc-committers@freebsd.org cc: des@freebsd.org cc: cvs-doc@freebsd.org Subject: Re: cvs commit: doc/en_US.ISO8859-1/books/handbook/disks chapter.sgml X-BeenThere: cvs-all@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: CVS commit messages for the entire tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 08 May 2003 08:24:09 -0000 On Wed, May 07, 2003 at 06:59:44PM -0700, Wes Peters wrote: > On Wednesday 07 May 2003 10:04, John Baldwin wrote: > > On 07-May-2003 David Schultz wrote: > > > I don't think that there's any requirement that FreeBSD > > > documentation read like a Henry James novel. Some people have > > > colorful writing styles that involve words such as > > > ``automagical'', ``moot'', and ``kludge'', and I'm not convinced > > > that this is a problem. Documentation isn't my domain, so I won't > > > stick my nose into this any further, but unless our translators > > > and other non-native English speakers have major qualms about > > > this kind of detail, I do consider this to be gratuitous. > > Agreed. automagical is a favorite word of several folks and does > > have a slightly different connotation from just 'automatic'. :) > In general, documentation sweeps to "clean up" somewhat colorful uses of > language are not a good idea. All whining about producing a > professional product aside, most of us work on FreeBSD because it > pleases us. One of these days I'm going to go put the BUGS sections > back in the AIO man pages and behead anyone who removes them again, for > instance. A comment from someone standing a bit outside, if I may... There are two different issues, here, I think, which call for different responses. On the one hand is "colorful" langauge, and on the other is ambiguous or needlessly confusing language. Colorful neologisms need not be a large problem. Should a reader encouter such a thing as "automagical" with which s/he is not familiar, it should not be terribly difficult to recognize it as a neologism and discover or deduce the appropriate meaning. On the other hand, _ambiguous_ terminology is almost always a bad thing in documentation, as such can easily lead the reader to _believe_ that s/he understands the point, while in fact having an understanding that is entirely different than what was intended. IMO, using 'moot' to mean 'irrelevant' is just such case, for the reasons already noted by others. -- greg byshenk - gbyshenk@byshenk.net - Leiden, NL hate spam?