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

[rurpy at yahoo.com]

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

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

> it's pretty clear
> that you have trouble reading things without mixing them up with
> your own preconceptions, but we already knew that.111

> > Maybe if comments like this were encouraged and acted upon
>
> do you think your posts would look any different if we replaced you
> with a markov generator and fed it with your old posts ?
>
> if you want to contribute, contribute.  a new tutorial would be great.
> get to work!

I don't want to, and probably couldn't, 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.  For example, the
sentence in question,

  "There are two new valid (semantic) forms for the
  raise statement: "

could be replaced with

  "There are two other forms for the raise statement
  in addition to the one described in chapter 8:"

or

  "Two new forms for the raise statement were introduced
  in Python verion 2.x:"

depending on what the meaning of "new" is in the
original sentence.  (I'm still not sure, but your post
implies it is the former.)

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.