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

[Andrew Bennetts]

On Tue, May 04, 2004 at 04:54:30PM -0700, Stephen Ferg wrote:
> I've been wondering how we can improve the quality of the Python
> documentation.
> 
> 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.

The Python docs accepts contributions exactly the same way the Python
interpreter and library does: by patches and bugs submitted to the
SourceForge tracker (take a look, there have been quite a few there).

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

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

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

Sorry, if the official docs lack sufficient description and examples to be
clear on how to use a sort function, then the docs should be fixed by
someone willing to spend the time to write a coherent addition to (or even
just rewording of) the existing documentation, not augmented by twenty times
as much commentary on randomly varying related topics.  As a reader, I
prefer properly written and edited and officially approved documentation to
ten pages of advice from people I don't know and trust -- I've often seen
well-meaning novices give bad advice on newsgroups and mailing lists.

As a reader, I also don't want to see a tutorial when I'm looking for
reference documentation.  Thus most of those comments are completely
irrelevant to me a lot of the time.

In fact, those comments look like conversations that already occur on the
newsgroup -- which is already a community-driven documentation resource,
handily indexed by google.  Some of them look like recipes -- but we already
have http://aspn.activestate.com/ASPN/Python/Cookbook/ for that (and I've
never seen 30+ line functions for case-insensitive sorting in our
cookbook).

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

I've never felt that the Python documentation was particularly lacking,
and searching google has always filled in few the gaps for me.  I guess
you're trying to solve a problem I don't have.  Maybe I'm unusual.

-Andrew.