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

[Stephen Ferg]

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.

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.

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?

-- Steve (Stephen Ferg ... Steve at Ferg.org)

---------------------------------------------------------------

Here are some recent posts on this subject.

---------------------------------------------------------------


from: 
http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&selm=6afpj1-qbb.ln1%40home.rogerbinns.com

I have found *by far* that the best docs are for PHP. It has little to
do with the actual official content (which is fairly complete and well
written and almost always includes an example), but a lot to do with
how anybody can nnotate the pages, wiki style.  Here is an example for
the sort function:
http://us2.php.net/manual/en/function.sort.php
Having all those comments is really helpful, and they also help for
updating the documentation.  If there are a lot of comments against a
page then the main body really needs some more work!

-------------------------------------------------------------

from:
http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&selm=mailman.150.1080693147.20120.python-list%40python.org

One thing I like about PHP's docs is that it allows users to post
comments, sugestions, extra information, etc to the docs online. Now
and then someone goes through and edits the useful bits into the
official documentation and flushes the comments all back out leaving
them clear for new people to post their own. Several times I've
attached comments as to how to compile a module or use some poorly
documented feature and have had lots of people write to thank me for
how helpful those comments were. I'd imagine the same process could be
useful in Python.

-----------------------------------------------------------

from:
http://www.python.org/cgi-bin/moinmoin/PythonDocumentation

Discussion 

Please!! get a wiki running side-by-side with the docs: e.g. one
corresponding wikiable page for every page here in the pydocs. The
startup data is simply that of the docs, so just mirror their
structure. Then after the wiki docs start offering lots of useful
information, the actual doc writers can incorporate this. To
summarize, I think Python's documentation (like the library reference)
is basically a big melange of api data and some snippets of useful
info. This wiki will help replace those places that just use API data
to fill up space, and turn it into something better.

Like the PHP Manual at http://www.php.net/. 


I think that's a great idea. But I think it should appear on a
separate wiki. We're going to need to do some steering for this wiki:
If every python-related project in the world tries to make their wiki
a walled garden within this wiki, we're going to run into problems.
RecentChanges will be a total mess of a zillion projects. Let's talk.
-- LionKimbro 2003-10-02 03:15:01