Date: Wed, 13 Jun 2001 17:19:02 -0700 From: Dima Dorfman <dima@unixfreak.org> To: Nik Clayton <nik@FreeBSD.org> Cc: Chern Lee <chern@meow.osd.bsdi.com>, freebsd-doc@freebsd.org Subject: Re: Style/Grammar/Writing Guidelines Message-ID: <20010614001902.C8F653E0B@bazooka.unixfreak.org> In-Reply-To: <0106140037160N.37769@clan.nothing-going-on.org>; from nik@FreeBSD.org on "Thu, 14 Jun 2001 00:37:16 %2B0100"
next in thread | previous in thread | raw e-mail | index | archive | help
[ Picking a rather random message to reply to. ] I think the important thing here is for the Handbook, and preferable for the rest of the doc/ tree, is to be *consistent*. There's nothing wrong with a personal tone; I think the problem is that right now we have a mix of tones. Personally, I'd prefer a more formal tone; I have a habit of using one, sometimes even in personal communications such as e-mail. I also removed all instances of the pronoun "I" except where properly attributed; those were really ugly :-). Nik Clayton <nik@FreeBSD.org> writes: > On Wednesday 13 June 2001 10:53 pm, Chern Lee wrote: > > I'm helping read over the handbook in order to prep it for its next > > edition of the printed version. > > > > I feel this applies to not only the printed version, but also the > > handbook as a whole, and any other documentation we have. > > > > In reading the first two chapters, I've noticed that a lot of it is very > > loosely written--especially the second. This occurs throughout the > > handbook. > > True. This is because of the large number of contributors. Right. I'd also like to take this time to point out that if we do write a style, it will have all the problems of style(9) and some of its own. The biggest problem with style(9) is that quite a few people don't agree with it; this would be even more the case with English, which isn't as structured as C is. Moreover, it isn't possible to write a style for English, because everybody writes differently; such is English I think what would be nice is to have a general policy of using a formal tone, and enforce it as much as feasible. For this to really work we'd have to fix all the "breakage" in the current documents, because inconsistent tone is worse than personal tone, IMO. Dima Dorfman dima@unixfreak.org To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010614001902.C8F653E0B>