Date: Fri, 4 Oct 2002 23:20:19 -0400 From: Tom Rhodes <trhodes@FreeBSD.org> To: Bob Johnson <stest030@garbonzo.hos.ufl.edu> 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>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, 4 Oct 2002 23:05:18 -0400
Bob Johnson <stest030@garbonzo.hos.ufl.edu> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20021004232019.32e665b9.trhodes>