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

[John Roth]

"Stephen Ferg" <steve at ferg.org> wrote in message
news:b16e4ef7.0405041554.33a03c05 at posting.google.com...
> I've been wondering how we can improve the quality of the Python
> documentation.

Frankly, I think it's pretty good as it stands. There are some places
where it could be improved: documenting new style classes is an
outstanding example, but by and large it's better than most efforts
I've seen.

> The problem with the Python documentation is that it is not being
> handled like an open source product.  The hallmark of open-source
> development is that many people contribute.  The Python docs in
> contrast are being maintained by a very small group.

You're confusing process with result.

> I'm sure that many people would like to contribute to the improvment
> of the documentation... the problem is that there is no way that they
> can do so easily. The solution is to move to a different model of the
> documentation process, by developing a way to make it easy for
> everyone in the Python community to contribute to the documentation.
>
> One solution is a documentation wiki: see the request (below) for a
> "corresponding wikiable page for every page here in the pydocs."  A
> similar but better solution is to follow the model created by the PHP
> community.  If you follow the link to
> http://us2.php.net/manual/en/function.sort.php  you'll see how
> impressive the results can be. Something like this is clearly what we
> need.

I've looked at it. I'll certainly say it's impressive, but I doubt if
my impression is what you though it would be.

> So I put this question to the entire Python community.  Can we create
> an interactive site, and the supporting organizational infrastructure,
> that will enable everyone in the Python community easily to contribute
> to the Python documentation?

As Andrew commented, there's nothing stopping you from
contributing. There's also nothing stopping you from setting
up a wiki yourself so people can comment on various pages
of the official documentation.

John Roth
>
> -- Steve (Stephen Ferg ... Steve at Ferg.org)
>