From owner-freebsd-doc Fri Oct 4 20:23:16 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 CDE4337B401 for ; Fri, 4 Oct 2002 20:23:13 -0700 (PDT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0939243E42 for ; Fri, 4 Oct 2002 20:23:13 -0700 (PDT) (envelope-from trhodes@FreeBSD.org) Received: from localhost ([192.168.0.5]) by pittgoth.com (8.12.6/8.12.5) with SMTP id g953NCwi048790; Fri, 4 Oct 2002 23:23:12 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Fri, 4 Oct 2002 23:20:19 -0400 From: Tom Rhodes To: Bob Johnson Cc: FreeBSD-doc@FreeBSD.org Subject: Re: Plea to the doc team Message-Id: <20021004232019.32e665b9.trhodes@FreeBSD.org> In-Reply-To: <200210042305.18970.stest030@garbonzo.hos.ufl.edu> References: <20021004212757.2a7e3227.trhodes@FreeBSD.org> <200210042305.18970.stest030@garbonzo.hos.ufl.edu> X-Mailer: Sylpheed version 0.8.1claws (GTK+ 1.2.10; i386-portbld-freebsd4.7) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit 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 Fri, 4 Oct 2002 23:05:18 -0400 Bob Johnson wrote: > 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 > technical documentation as it is a user manual. There is a > difference. It should be designed to make the user comfortable with > the information being presented. Agreed. > > > 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 > > if an example were provided of how one can "cut down extremly" > by eliminating the offending pronoun, the issue could be clarified. > One envisions a great deal of passive voice creeping in as a result of > > this policy. Actually, as pointed out after I sent this email, 'you' is fine, but putting 'you' in every other sentence does not look nice. By presenting a set of steps in a more straightforward fashion then filling the sentence with 'you this and you that' along with some extra boring and unneeded words can enlarge a paragraph ten fold. My recent change took a long paragraph (that used a run-on sentence, repeated a phrase twice although once in different words, and putting a different file system in each of the parts really sounded bad. Instead, I listed what needed to be done to what file systems. Quick, direct, simple. After my re-read, it looked much better ;) > > > > > 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 I actually am taking a class (for the first time in ten years) > this term, I have no excuse. I'll try to cover a chapter or two. Thanks for the help! > > > > > 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 > -- Tom (Darklogik) Rhodes www.FreeBSD.org -The Power To Serve www.Pittgoth.com -Pittgoth Discussion Portal trhodes@{Pittgoth.com, FreeBSD.org} PGP key by www: http://www.pittgoth.com/~darklogik/darklogik.key To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message