[Python-ideas] Order in the documentation search results
Giampaolo Rodolà
g.rodola at gmail.com
Mon Dec 31 00:38:54 CET 2012
2012/12/30 Hernan Grecco <hernan.grecco at gmail.com>
> 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
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> http://mail.python.org/mailman/listinfo/python-ideas
>
+1
I agree it's sub-optimal.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20121231/96191d62/attachment.html>
More information about the Python-ideas
mailing list