It's hard to find documentation

[Fernando Pérez]

Brad Bollenbach wrote:

> I'm well aware of pydoc. Using your instructions on how to use it,
> we /still/ aren't able to locate the top-level document Bruce was
> interested in:
> 
> mothra at mothra:~$ python2.1
> Python 2.1.1 (#1, Nov 11 2001, 18:19:24)
> [GCC 2.95.4 20011006 (Debian prerelease)] on linux2
> Type "copyright", "credits" or "license" for more information.
>>>> from pydoc import help
>>>> help("Extending and Embedding the Python Interpreter")
> no Python documentation found for 'Extending and Embedding the
> Python Interpreter'
> 
You are right. pydoc isn't perfect yet, I think its indexing 
algorithm still has room for a lot of improvement. But there's a 
solid base to start from.

>>> If I wanted it badly enough, I would have done so already. :)
>> 
>> Ka-Ping Yee already did.
> 
> Kudos to Ka-Ping Yee. He obviously wanted it more than I did, but it
> still doesn't provide the extreme ease of use (particularly for
> accessing top-level documents with minimal effort) that, for
> example, perldoc does. (That isn't a Perl plug, but the name "pydoc"
> implies that it wanted to be Python's equivalent of perldoc.)

Agreed. I love the html form of pydoc for module browsing, but I do 
miss the ease of finding general info with perldoc. Another minor 
gripe is that when running pydoc -g, the search box almost never 
finds what I want (plus it's dog slow). I never use it, I just fire 
it up so the server runs and then click my way through the top-level 
module list.

So to summarize this whole discussion (maybe in the future someone 
from the doc team can use this):

1) The 'search' at www.python.org is a perfectly useless piece of 
junk. It would be better to remove the search option altogether and 
just tell people to use google. Maybe in the future the 'ultraseek' 
joke can be replaced with a site-local google.

2) Pydoc is great, but could stand improvement in its indexing/search 
capabilities. Ideally, after a search it would return hierarchically 
organized results (top-level docs, pages, modules, function 
docstrings, etc). Returning this as a webpage (it already has a 
server) would be great.

3) The written html docs are top-quality, but they lack a bit in 
cross-referencing (though the general indices at the end of each are 
*extremely* good). Fixing this is slow and time-consuming, and can 
really only be done by someone who knows both python and the 
documentation very well.

I think (1) should be very easy to fix (and should be a priority of 
the site maintainers IMHO), (2) requires coding work but sounds like 
a fairly interesting project. Moderately difficult, but not 
impossible by any means. (3) I suspect will be the slowest to improve.

Just my thoughts,

f.