Date: Fri, 4 Oct 2002 22:40:09 -0400 From: Tom Rhodes <trhodes@FreeBSD.org> To: "Greg 'groggy' Lehey" <grog@FreeBSD.org> Cc: FreeBSD-doc@FreeBSD.org Subject: Re: Plea to the doc team Message-ID: <20021004224009.3b1f404b.trhodes@FreeBSD.org> In-Reply-To: <20021005023128.GG83766@wantadilla.lemis.com> References: <20021004212757.2a7e3227.trhodes@FreeBSD.org> <20021005020608.GE83766@wantadilla.lemis.com> <20021004221936.5b91d9b2.trhodes@FreeBSD.org> <20021005023128.GG83766@wantadilla.lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sat, 5 Oct 2002 12:01:28 +0930
"Greg 'groggy' Lehey" <grog@FreeBSD.org> wrote:
> On Friday, 4 October 2002 at 22:19:36 -0400, Tom Rhodes wrote:
> > On Sat, 5 Oct 2002 11:36:08 +0930
> > "Greg 'groggy' Lehey" <grog@FreeBSD.ORG> wrote:
> >
> >> On Friday, 4 October 2002 at 21:27:57 -0400, Tom Rhodes wrote:
> >>> Fellow Doc committers and contributers,
> >>>
> >>> Its been said over and over the use of 'you' in technical docs
> >looks>> bad.
> >>
> >> Many things have been said over and over. One should not believe
> >all> statements. Overly terse and obfuscatory language is also
> >> undesirable.
> >
> > Heavily undesirable.
> >
> >>> 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'.
> >>
> >> You should check spelling and other punctuation too.
> >
> > I'm doin this, trust me. ;)
>
> I was actually referring to one punctuation and two spelling errors in
> your text above.
Yes, I know. I'd be lost without ispell/aspell ;)
>
> >>> 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.
> >>
> >> Style is more than verbosity or lack of same.
> >>
> >> I'm not heavily involved in the doc project, but I'm seeing too
> >many> rule-based modifications. Yes, overuse of the second person
> >can be> annoying, but it must bee seen in context. I'd rather see
> >people> write documentation which is intelligible and useful rather
> >than> documentation which merely adheres to certain rules.
> >
> > To be honest, we have several areas where its easier to read having
> > less of:
> > 'you must do this. now you must do that. after this has been
> > done you can do this'
> >
> > could be reworded to:
> >
> > 'do this, then this, then
> > this, and its finished'
>
> In that case, it sounds fine. But I couldn't have guessed it based on
> what you said above.
Then the way I phrased it, compaired to the way I ment was
incorrect. I'm trying to kill repeating things. If something is
mentioned in paragraph 1, it should be mentioned in paragraph 2 and
4. Unless of course there is an important reason hehe.
>
> > The other day I read an area in our handbook which had alot of
> > useless words and it was so long and dull. Much of our docs should
> > be correct and on the mark. Not filled with 'padding' if you will.
>
> Sure, there's a lot of room for improvement in the style in the book.
> I'm just concerned that saying "don't use 'you'" is liable to start a
> witch-hunt for that particular issue, rather than looking at the text
> as a whole.
>
> I'm reminded of this:
>
> William Safire's Rules for Writers:
>
Another good source is Quick Access Reference For Writers which is
alot like the above ;) Have no fear for a witch hunt, right now I'm
trying to clean up the things that bothered me. Its horrible when
you try to do something, and then read a bloated text on the issue,
only to review what you've done and say 'that could have been done
by listing the step and then telling me whats going on afterwords.'
We'll get there eventually ;)
>
> Greg
> --
> See complete headers for address and phone numbers
>
--
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?20021004224009.3b1f404b.trhodes>