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

[Michael Geary]

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

A good example of this just came up in this group a few days ago. A new
Python programmer was puzzled over this result:

>>> text = 'zone "newsouthpine.com" {'
>>> text.lstrip("zone \"")
'wsouthpine.com" {'

He did read the documentation for lstrip, but the doc doesn't make it at all
clear that the argument to lstrip is treated as a set of characters.

With the PHP documentation model, there would have been a user comment and
example attached to the lstrip doc explaining this.

Asking for patches and comments via Sourceforge is nowhere near as effective
as having a comment box right on the doc page. Someone has to be really
motivated to take the trouble to go to SF to submit a comment. A comment box
makes it easy.

-Mike