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

[Marcel Molina Jr.]

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.

[..snip..]

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

if php's documentation is being presented as a sort of model in this
thread, then i would like to mention what *i* find the most helpful aspect
of its documentation system, far apart from there being a comment posting
system at the bottom of each page, which has been (as far as i can tell)
the primary feature that people would like adopted by python.

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

if you mistype <function name> (by putting an underscore, say, where there
is none, or visa versa), then you are presented with a page of the 20
closest matches. this can be taken advantage of when there are a set of
functions that all share the same prefix (say 'str' or 'pg' or 'array').

in addition, once you have made it to the function you are looking for,
the notion of categories is reflected in the left menu which will note
that you are on an "str' type function and will then list all string
functions for you.

the sites 404 handling also extends to more than built in function
detection.  if you go to php.net/operators you are redirected to the
gateway to all documentation on operators. on the left, it provides a
menu of all other such gateway pages in the same categorical section
of the languages documentation, so there are links to similar gateway
pages such as "types", "variables", "constants", "control structures",
"classes and objects", etc. it recognizes from what "height" you are
approaching the language, which is helpful. in the case of a specific string
function (as mentioned above) it lists all string functions, in the case of
being on the operators page, it lists all other fundamental language
documentation pages.

this is not to say that this is revolutionary or unique. i suspect
(without the aid of explicitly *remembering*) that most language
documentation provides these things. my point about php's iteration of
this, though, is that the interface is very intuitive. it does a good job of
being psychic. this approach may used with other documentation systems, i
just don't know about them.

going to google will often get you within three clicks of what you are
looking for. that is pretty good. php's website often gets me to what
i am looking for in one try, though. when one is focusing on the problem
at hand, and making frequent documentation enquiries, getting to the
answers as quick as possible allows one to keep their thoughts primarily
on what the problem/question is, rather than having to break off and think
about the best ways of trying to find a given piece of documentation.

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.

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 think ruby's "ri" is really great, though much of that functionality
seems to be more or less built into python through dir() and __doc__,
et al.

Summary:

php's web site affords the user a flexible approach toward accessing
documentation. once you actually *get there*  you might like to have
comments at the bottom of the page, or you might like, on the other hand,
a more "official" reference style approach. regardless, though, you have
to *get there* first and php's website makes that very fast and intuitive.

i don't have issues with python's documentation, per se, the way that
the person who started this thread does. i just wanted to mention the
thing that i like about php's documentation which no one else has seemed
to mention.

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