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

[rurpy at yahoo.com]

"Fredrik Lundh" wrote:
> 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 ?

The word "you".

> >   "...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 wasn't commenting on the advisability of deprecating a
particular form of the raise statement.  So why would I
leave that irrelevant material in the quote?  I was commenting
on your remarks that the OP "read the tutorial backwards".
And pointing 1) there really was a specific problem in the
tutorial docs.  2) that a contributing factor was that there is
no good language reference.  3)  That your caustic comments
were unwarranted and have a negative effect on people's
willingness to point out and fix doc problems.

> > 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.

What are you saying?  Ideas must come only from those
with the time and skill to implement them?  No one else
need apply?

Whenever anyone criticizes anything about free software
there are three automatic responses:

1. You are an idiot if you can't understand / have a problem with that.
2. Its free so you should be grateful and shutup.
3. You have the source, change it yourself, you lazy whiner.

You could save everyone time and bandwidth by just
responding with "#3!!!"

Sorry Fredrik, truth is truth.  If there is a problem then people
are right to point it out.  If that is really a big problem for
you then I suggest setting up a forum or mailing list on
python.org where you can delete "improper" messages,
and ban posters who have "incorrect" attitudes.

> 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.

What makes you think there is such a way?  Don't you
think publishers have been looking for that way for years?
Do you think it possible that a good manual might just
require good writers, and good editors, and it would make
sense to encourage those who might be interested, rather
than posting put-downs of anyone who misreads or
misinterprets the docs?

> 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.

Yes, here comes #3.  I am not ignoring that at all.  I am very
applicative.  But that appreciation does not extend to
supplication, or censorship.  And save your name-calling for
someone who is bothered by it.

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

In the time you've spent posting about this, you or someone
else with svn access to the docs, could have simply gone
and made the change.  Admittedly most changes would
require more process but there are many like this just require
someone to DO IT.  Give me svn access, and I will.  But I
guess for you it is more fun to write wikis and things than
actually fixing the doc.  (Don't get me wrong, I hope the
wiki thing works and I will contribute but note what I wrote
initially about programming Python being more fun than
dealing with that grungy english *writing* yeck!)