
Hi, On Sun, Dec 30, 2012 at 7:54 PM, Hernan Grecco <hernan.grecco@gmail.com>wrote:
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
I experimented with this a bit a while ago. See http://bugs.python.org/issue15871#msg170048. Best Regards, Ezio Melotti