Mailman 3 Order in the documentation search results - Python-ideas

31 Dec 2012

      Hi,

I have seen many people new to Python stumbling while using the Python
docs due to the order of the search results.

For example, if somebody new to python searches for  `tuple`, the
actual section about `tuple` comes in place 39. What is more confusing
for people starting with the language is that all the C functions come
first. I have seen people clicking in PyTupleObject just to be totally
disoriented.

Maybe `tuple` is a silly example. But if somebody wants to know how
does `open` behaves and which arguments it takes, the result comes in
position 16. `property` does not appear in the list at all (but
built-in appears in position 31). This is true for most builtins.

Experienced people will have no trouble navigating through these
results, but new users do. It is not terrible and at the end they get
it, but I think it would be nice to change it to more (new) user
friendly order.

So my suggestion is to put the builtins first, the rest of the
standard lib later including HowTos, FAQ, etc and finally the
c-modules. Additionally, a section with a title matching exactly the
search query should come first. (I am not sure if the last suggestion
belongs in python-ideas or in
the sphinx mailing list, please advice)

Thanks,

Hernan

Order in the documentation search results

Hernan Grecco

tags

participants (10)