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

[John Roth]

"Marcel Molina Jr." <marcel at vernix.org> wrote in message
news:mailman.274.1083773846.25742.python-list at python.org...
> 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.

> what really makes sense for me with php's documentation is how very
> intuitive (and therefore  easy and fast) it is to get to what one is
> looking for. this is particularly true of its online documentation of
> its built in functions. this ease of access is leveraged through their
> website's way of dealing with 404 requests.
>
> if you go to php.net/<function name> you are automatically redirected
> to the page that documents that function.
>
> this is often more efficient than the three step process of going to
> the page, doing a search, clicking on the appropriate search result. it
> is often faster than have a bookmark to a page that lists all functions
> and then scrolling or even Ctrl-Fing your way to the appropriate one.

[snip]

> online documentation shouldn't be one's only recourse though, and
> this is a place where python has a major leg up on php. one aspect to
> python's documentation that i really appreciate is having the help()
> function interface to pydoc now in the interpreter. whether it be ruby's
> 'ri', perl's 'perldoc' or python's 'pydoc', command line interfaces to
> documentation are very helpful, both as a learning tool and a reference,
> especially when they can be accessed from within an editor such as with
> vi's Shift-K macro. php has no such interface.

I kind of like this notion. There are a lot of times I'm going for a
module that I know is there, but I'm not sure of either the name or
the location in the TOC. (And the trick of cleverly hiding
the module index at the back of the Library Reference instead of
leaving it as a separate document got me confused for a while, but
that may be a WinHelp issue.)

> pydoc from the interpreter through 'help()' often gets me to where i want
> to go in one step, so no complaints there. it would be nice, though,
> if there was the same kind of web site functionality at python.org
> as there is at php.net (though i am not familiar with all the ways to
> access documentation for either and there may be many means of getting
> documentation that address my need that i am just not aware of).

I vaguely remember that there were ways of rigging WinHelp so that
it would do something similar, at least if you asked nicely. The
difficulty is probably getting the doc process to produce the right
incantations.

John Roth
>
> thanks,
> marcel
> -- 
> Marcel Molina Jr. <marcel at vernix.org>
>