Date: Fri, 4 Oct 2002 23:05:18 -0400 From: Bob Johnson <stest030@garbonzo.hos.ufl.edu> To: Tom Rhodes <trhodes@FreeBSD.org>, FreeBSD-doc@FreeBSD.org Subject: Re: Plea to the doc team Message-ID: <200210042305.18970.stest030@garbonzo.hos.ufl.edu> In-Reply-To: <20021004212757.2a7e3227.trhodes@FreeBSD.org>
index | next in thread | previous in thread | raw e-mail
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. > 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. > > 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. > > 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 messagehome | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200210042305.18970.stest030>