Doc suggestions (was: Why "class exceptions" are not deprecated?)

[Fredrik Lundh]

rurpy at yahoo.com wrote

> Fredrik Lundh wrote:
> > rurpy at yahoo.com wrote:
> >
> > > The OP points out an ambiguity in the docs, and as usual,
> > > gets told he can't read, etc.  How typical.
> >
> > where did anyone tell the OP that he can't read?
>
>   "it could be that the tutorial author expected you
>   to read chapter 8 before you read chapter 9,..."

What makes you so sure that wasn't a statement about the tutorial ?

>   "...because some random guy on a newsgroup read
>   the tutorial backwards..."

Does the word "context" mean anything to you?  or the word "de-
precation", that was used multiple times by the OP ?  Or the phrase
"changing the language", that you cut out from that quote.

> I don't want to, and probably couldn't

That's pretty obvious.

> write a tutorial as good as what is already there.  But what I can
> do is report problems I find when using it, and make suggestions
> about how to avoid those problems.

There's no shortage of ideas -- nor people who can write a tutorial
that's better than the current one (which is far from optimal, mostly
thanks to a zillion peephole edits over the years).  There's a shortage
of volunteer time, though.  That's why the "I'm just the idea guy,
someone else will have to provide the hundreds of hours required
to implement my idea" arguments are so offensively meaningless.

Come up with an idea that *reduces* the overall work needed to write
and maintain a good manual, and people might start listening to what
you have to say.

Or come up with some money.  If you can fund a technical writer for
one year, there are lots of things that could be done.

> But the perception I get here, from responses like yours,
> is that such suggestions are unwelcome, and unlikely
> to be acted upon.  I gather corrections of factual
> errors are welcome, but stylistic, or organizational
> ones are not.  And the latter kind of changes, applied
> extensively to all the docs, are what will make a big
> improvement.  Difficult at best, but absolutely impossible
> if you and the other powers-that-be are happy with
> the status-quo.

The problem with people like you is that you are completely ignoring
all the hard work done by the people who build the free stuff that
anonymous cowards like you like to complain about.

Luckily, most people are not like you.  If they were, nothing would
ever happen.

</F>