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> References: <20021004212757.2a7e3227.trhodes@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200210042305.18970.stest030>