Date: Thu, 8 May 2003 10:22:39 +0200 From: Greg Byshenk <gbyshenk@byshenk.net> To: Wes Peters <wes@softweyr.com> Cc: cvs-doc@freebsd.org Subject: Re: cvs commit: doc/en_US.ISO8859-1/books/handbook/disks chapter.sgml Message-ID: <20030508082239.GC64674@core.byshenk.net> In-Reply-To: <200305071859.44725.wes@softweyr.com> References: <XFMail.20030507130410.jhb@FreeBSD.org> <200305071859.44725.wes@softweyr.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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? <http://www.cauce.org>; <http://www.byshenk.net/ive.been.spammed.html>;
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030508082239.GC64674>