From owner-freebsd-doc Fri Oct 4 20: 5:54 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 DCB8437B401; Fri, 4 Oct 2002 20:05:52 -0700 (PDT) Received: from smtp.ufl.edu (sp16en1.nerdc.ufl.edu [128.227.74.16]) by mx1.FreeBSD.org (Postfix) with ESMTP id 2BD0243E3B; Fri, 4 Oct 2002 20:05:52 -0700 (PDT) (envelope-from stest030@garbonzo.hos.ufl.edu) Received: from bobj.dyndns.org (cpe-gan-68-101-90-216-cmcpe.ncf.coxexpress.com [68.101.90.216]) (authenticated bits=0) by smtp.ufl.edu (8.12.6/8.12.6/2.4.0) with ESMTP id g9535isw036008 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO); Fri, 4 Oct 2002 23:05:46 -0400 Content-Type: text/plain; charset="iso-8859-1" From: Bob Johnson To: Tom Rhodes , FreeBSD-doc@FreeBSD.org Subject: Re: Plea to the doc team Date: Fri, 4 Oct 2002 23:05:18 -0400 X-Mailer: KMail [version 1.4] References: <20021004212757.2a7e3227.trhodes@FreeBSD.org> In-Reply-To: <20021004212757.2a7e3227.trhodes@FreeBSD.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Message-Id: <200210042305.18970.stest030@garbonzo.hos.ufl.edu> X-Scanned-By: NERDC Open Systems Group (http://open-systems.ufl.edu/services/virus-scan/) 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 04 October 2002 09:27 pm, Tom Rhodes appears to have written: > Fellow Doc committers and contributers, > > Its been said over and over the use of 'you' in technical docs looks > bad. 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'. > Perhaps, but it seems to me that the Handbook is not so much=20 technical documentation as it is a user manual. There is a difference. =20 It should be designed to make the user comfortable with the information=20 being presented. > 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. It isn't clear to this writer how this is to be accomplished. Perhaps=20 if an example were provided of how one can "cut down extremly"=20 by eliminating the offending pronoun, the issue could be clarified.=20 One envisions a great deal of passive voice creeping in as a result of=20 this policy. > > If you have nothing to do between classes, please print a section > of the handbook and skim it. See where we use to many words, > where paragraphs can be more clear or even where we make grammar > mistakes. Then committers please make > the changes or contributers please create a patch file for us. I guess I've been a bit lax about this for the past year or two. Since=20 I actually am taking a class (for the first time in ten years) this=20 term, I have no excuse. I'll try to cover a chapter or two. > > We could also use some 5.0 information. Currently we seem to lack > documentation on ACPI, device.hints(5), mail clients (I'm working) > STMP auth (I'm working) and various other features. > > Thanks to all who have read this far ;) My pleasure... - Bob To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message