From owner-freebsd-doc Fri Oct 4 19: 6:14 2002 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 BDD2237B401; Fri, 4 Oct 2002 19:06:12 -0700 (PDT) Received: from wantadilla.lemis.com (wantadilla.lemis.com [192.109.197.80]) by mx1.FreeBSD.org (Postfix) with ESMTP id 5F37443E75; Fri, 4 Oct 2002 19:06:11 -0700 (PDT) (envelope-from grog@lemis.com) Received: by wantadilla.lemis.com (Postfix, from userid 1004) id D4D2F81432; Sat, 5 Oct 2002 11:36:08 +0930 (CST) Date: Sat, 5 Oct 2002 11:36:08 +0930 From: Greg 'groggy' Lehey To: Tom Rhodes Cc: FreeBSD-doc@FreeBSD.org Subject: Re: Plea to the doc team Message-ID: <20021005020608.GE83766@wantadilla.lemis.com> References: <20021004212757.2a7e3227.trhodes@FreeBSD.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20021004212757.2a7e3227.trhodes@FreeBSD.org> User-Agent: Mutt/1.4i Organization: The FreeBSD Project Phone: +61-8-8388-8286 Fax: +61-8-8388-8725 Mobile: +61-418-838-708 WWW-Home-Page: http://www.FreeBSD.org/ X-PGP-Fingerprint: 9A1B 8202 BCCE B846 F92F 09AC 22E6 F290 507A 4223 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org On Friday, 4 October 2002 at 21:27:57 -0400, Tom Rhodes wrote: > Fellow Doc committers and contributers, > > Its been said over and over the use of 'you' in technical docs looks > bad. Many things have been said over and over. One should not believe all statements. Overly terse and obfuscatory language is also undesirable. > While I'm going to be at working cleaning up the doc tree of bad > gammar (run-ons, incorrect use of semicolons, to many useless words > and fragments) I'll try to kill the use of 'you'. You should check spelling and other punctuation too. > My request is, if you remove the 'you' from documents you can cut > down extremly on the amount you type, the amount a reader will read, > and documentation size in general. This IMO is a good thing and > will also cut down on grammar bogons. Style is more than verbosity or lack of same. I'm not heavily involved in the doc project, but I'm seeing too many rule-based modifications. Yes, overuse of the second person can be annoying, but it must bee seen in context. I'd rather see people write documentation which is intelligible and useful rather than documentation which merely adheres to certain rules. Greg -- See complete headers for address and phone numbers To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message