[docs] Documentation Search Hard to Use

Jason Kotenko kotenko at gmail.com
Wed Aug 25 20:55:21 CEST 2010


I have an improvement suggestion, which you may or may not agree with. 
I personally find the search function on the docs.python.org site to
pretty difficult to use effectively.  If you do a search, it appears
that you get results first from method/class/package/etc names, ordered
lexicographically, then you get a section of fulltext search results,
also ordered lexicographically, then finally a section of fulltext
results from various HowTo's and FAQs.  There is no indication of the
change between these sections, this is just from observation.

My issue is that I have no way of picking out which results are the most
relevant.  If I use a search term like xml for instance, I first get
every keyword result from the names of things like
classes/packages/methods, which is a lot of things.  Even down in the
fulltext results, I have no indication of relevance, everything is
ordered by lexicography, which means that items in Chapter 1 come first,
then Chapter 10-19, then Chapter 2, then Chapter 20-29, ... , and on and
on.  Same with the FAQ/HowTo results.

I'm wondering if there is a reason for using results such as these and
not a more typical relevance based search?  In fact you could still list
the names of things at the top, put a divider, and do relevance on the
fulltext entries, if you still want the name based things.  I have a
Xapian powered search on a site I manage that does it quite capably and
with lightning speed.

As it stands now, I use the index to find things if I know what they are
called, and otherwise have to open a new tab and use Google.  However,
if I'm looking for docs just on Python 3.x for instance, the query "xml
site:docs.python.org/py3k" yields only one result (I wonder, is
robots.txt set up to not index it?).  So that means I'm more likely to
do "xml site:docs.python.org" and then click the link and change the
path to say "py3k" after the domain.

I know you guys probably have a lot to do - is there any way I can
assist in this area?


More information about the docs mailing list