improving the Python docs -- a wiki? copy PHP's model?

[Stephen Ferg]

> Is submitting a bug or patch to sourceforge really that much of a barrier?

Yes, it is a significant barrier.  It requires knowledge of both Latex
and a certain way of using diff.  There are many, many Python users --
especially Python-on-Windows -- who are not familiar with these
technologies and don't have the time to learn them for the sole
purpose of making a contribution to the documentation.

> As a reader, I
> prefer properly written and edited and officially approved documentation to
> ten pages of advice from people I don't know ...

I agree.  But there are gaps in the documentation, where the
officially approved documentation is silent.  In such cases, I prefer
advice from others, even though I've never met them, to no help at
all.

After all, what is comp.lang.python except advice from people that
you've (for the most part) never met. :-)


> I've never felt that the Python documentation was particularly lacking...

In general, I'd agree that the Python documentation is outstanding. 
But there are gaps -- a qualifying phrase here, a missing reference
there, a small example in many places.  Filling those gaps would make
the difference in those places between documentation that is just
barely adequate and documentation that is really excellent.

For experienced Pythonistas, this difference may be merely a minor
matter of convenience, but for newbie Pythonistas this may be the
difference between usable and not usable.  And we want to support
newbies.  We want to attract as many of them as possible.  The larger
the newbie population today, the larger the active, experienced Python
community tomorrow.

And remember, it is the newbies who are finding the problems in the
documentation... they are the ones reading it, because they are the
ones that need it.  As newbies, they may not yet be masters of all the
supporting technologies we use (see my earlier point about the
technical barriers being too high), but they are certainly the people
in the best position to find gaps in the documentation and to supply
material that others would find useful.

WE NEED TO MAKE IT EASIER FOR MANY HANDS -- INCLUDING NEWBIE HANDS --
TO CONTRIBUTE TO THE DOCUMENTATION.

The PHP model is a good one.  Many hands contribute online. 
Periodically, expert hands incorporate the best of the online
contributions into the mainline docs.