Order in the documentation search results
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
On 12/30/2012 12:54 PM, Hernan Grecco 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)
While we're on the topic, why in this day and age do we have a custom search? Using google site search would be faster for the user, and more accurate. --Ned.
Thanks,
Hernan _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
On 12/30/2012 07:11 PM, Ned Batchelder wrote:
On 12/30/2012 12:54 PM, Hernan Grecco 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)
While we're on the topic, why in this day and age do we have a custom search? Using google site search would be faster for the user, and more accurate.
I agree. Someone needs to propose a patch though. cheers, Georg
On 30.12.12 20:45, Georg Brandl wrote:
On 12/30/2012 07:11 PM, Ned Batchelder wrote:
On 12/30/2012 12:54 PM, Hernan Grecco wrote:
... I have seen many people new to Python stumbling while using the Python docs due to the order of the search results. ... 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)
While we're on the topic, why in this day and age do we have a custom search? Using google site search would be faster for the user, and more accurate.
I agree. Someone needs to propose a patch though. ...
a custom search in itself is a wonderful thing. To me it also shows more appreciation of visitor concerns than thoses sites, that are just _offering_ google site search (which is accessible anyway to every visitor capable of memorizing the google or bing or whatnot URL). I second Hernans suggestion about ordering and also his question where the request (and patches) should be directed to. All the best, Stefan.
Hi, Thanks for all the feedback. I was hacking the sphinx indexer and the javacript searchtool today. I think the search results can be improved by patching sphinx upstream and adding a small project dependent (in this case Python) javascript snippet. I have created a proposal in the Sphinx Issue tracker [0]. Let's move the discussion there. best, Hernan [0] https://bitbucket.org/birkenfeld/sphinx/issue/1067/better-search-results On Mon, Dec 31, 2012 at 8:47 AM, Stefan Drees <stefan@drees.name> wrote:
On 30.12.12 20:45, Georg Brandl wrote:
On 12/30/2012 07:11 PM, Ned Batchelder wrote:
On 12/30/2012 12:54 PM, Hernan Grecco wrote:
...
I have seen many people new to Python stumbling while using the Python docs due to the order of the search results. ...
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)
While we're on the topic, why in this day and age do we have a custom search? Using google site search would be faster for the user, and more accurate.
I agree. Someone needs to propose a patch though. ...
a custom search in itself is a wonderful thing. To me it also shows more appreciation of visitor concerns than thoses sites, that are just _offering_ google site search (which is accessible anyway to every visitor capable of memorizing the google or bing or whatnot URL).
I second Hernans suggestion about ordering and also his question where the request (and patches) should be directed to.
All the best, Stefan.
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
Hi hernan, On 02.01.13 12:20, Hernan Grecco wrote:
... Thanks for all the feedback. I was hacking the sphinx indexer and the javacript searchtool today. I think the search results can be improved by patching sphinx upstream and adding a small project dependent (in this case Python) javascript snippet. I have created a proposal in the Sphinx Issue tracker [0]. Let's move the discussion there. ... [0] https://bitbucket.org/birkenfeld/sphinx/issue/1067/better-search-results
thanks a lot for transforming the mail thread to improve the local search facility into real code suggestions. I commented on a first snippet from your suggested patch there. All the best, Stefan. Further historic details:
On Mon, Dec 31, 2012 at 8:47 AM, Stefan Drees <stefan@drees.name> wrote:
On 30.12.12 20:45, Georg Brandl wrote:
On 12/30/2012 07:11 PM, Ned Batchelder wrote:
On 12/30/2012 12:54 PM, Hernan Grecco wrote:
...
I have seen many people new to Python stumbling while using the Python docs due to the order of the search results. ...
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)
While we're on the topic, why in this day and age do we have a custom search? Using google site search would be faster for the user, and more accurate.
I agree. Someone needs to propose a patch though. ...
a custom search in itself is a wonderful thing. To me it also shows more appreciation of visitor concerns than thoses sites, that are just _offering_ google site search (which is accessible anyway to every visitor capable of memorizing the google or bing or whatnot URL).
I second Hernans suggestion about ordering and also his question where the request (and patches) should be directed to. ...
Hi, I have done some work to improve the search results on the Python Docs. You can compare the current [0] with the proposed [1], or both at the same time [2]. It is basically a patch for sphinx [4], plus a python specific javascript [3]. The ideas are briefly explained [4]. I have not optimized the scores in [4], just some educated guesses. best, Hernan [0] http://hgrecco.github.com/searchpydocs/current/ [1] http://hgrecco.github.com/searchpydocs/proposed/ [2] http://hgrecco.github.com/searchpydocs/ [3] https://github.com/hgrecco/searchpydocs/blob/master/cpy_scorer.js [4] https://bitbucket.org/birkenfeld/sphinx/issue/1067/better-search-results On Wed, Jan 2, 2013 at 1:37 PM, Stefan Drees <stefan@drees.name> wrote:
Hi hernan, On 02.01.13 12:20, Hernan Grecco wrote:
... Thanks for all the feedback. I was hacking the sphinx indexer and the
javacript searchtool today. I think the search results can be improved by patching sphinx upstream and adding a small project dependent (in this case Python) javascript snippet. I have created a proposal in the Sphinx Issue tracker [0]. Let's move the discussion there. ... [0] https://bitbucket.org/birkenfeld/sphinx/issue/1067/better-search-results
thanks a lot for transforming the mail thread to improve the local search facility into real code suggestions.
I commented on a first snippet from your suggested patch there.
All the best, Stefan.
Further historic details:
On Mon, Dec 31, 2012 at 8:47 AM, Stefan Drees <stefan@drees.name> wrote:
On 30.12.12 20:45, Georg Brandl wrote:
On 12/30/2012 07:11 PM, Ned Batchelder wrote:
On 12/30/2012 12:54 PM, Hernan Grecco wrote:
...
I have seen many people new to Python stumbling while using the Python docs due to the order of the search results. ...
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)
While we're on the topic, why in this day and age do we have a custom search? Using google site search would be faster for the user, and more accurate.
I agree. Someone needs to propose a patch though. ...
a custom search in itself is a wonderful thing. To me it also shows more appreciation of visitor concerns than thoses sites, that are just _offering_ google site search (which is accessible anyway to every visitor capable of memorizing the google or bing or whatnot URL).
I second Hernans suggestion about ordering and also his question where the request (and patches) should be directed to. ...
Hi Hernan, On 03.01.13 05:05, Hernan Grecco wrote:
... I have done some work to improve the search results on the Python Docs. You can compare the current [0] with the proposed [1], or both at the same time [2]. It is basically a patch for sphinx [4], plus a python specific javascript [3]. The ideas are briefly explained [4].
I have not optimized the scores in [4], just some educated guesses. ...
[0] http://hgrecco.github.com/searchpydocs/current/ [1] http://hgrecco.github.com/searchpydocs/proposed/ [2] http://hgrecco.github.com/searchpydocs/ [3] https://github.com/hgrecco/searchpydocs/blob/master/cpy_scorer.js [4] https://bitbucket.org/birkenfeld/sphinx/issue/1067/better-search-results
that looks good to me for eg. file, dict and dict.clear. Far better, than a google/bing/whatever_external search by the way (as tested with dict, using google search on "dict site:http://docs.python.org/3/") :-)) As I read in the sphinx issue mail flow you opened, Georg asks for a pull request of the patches. I consider this very promising. Thanks again for the effort and these good first results Hernan! All the best, Stefan. Further historic details:
On Wed, Jan 2, 2013 at 1:37 PM, Stefan Drees <stefan@drees.name> wrote:
Hi hernan, On 02.01.13 12:20, Hernan Grecco wrote:
... Thanks for all the feedback. I was hacking the sphinx indexer and the
javacript searchtool today. I think the search results can be improved by patching sphinx upstream and adding a small project dependent (in this case Python) javascript snippet. I have created a proposal in the Sphinx Issue tracker [0]. Let's move the discussion there. ... [0] https://bitbucket.org/birkenfeld/sphinx/issue/1067/better-search-results
thanks a lot for transforming the mail thread to improve the local search facility into real code suggestions.
I commented on a first snippet from your suggested patch there.
All the best, Stefan.
Further historic details:
On Mon, Dec 31, 2012 at 8:47 AM, Stefan Drees <stefan@drees.name> wrote:
On 30.12.12 20:45, Georg Brandl wrote:
On 12/30/2012 07:11 PM, Ned Batchelder wrote:
On 12/30/2012 12:54 PM, Hernan Grecco wrote: > > ... > > I have seen many people new to Python stumbling while using the Python > docs due to the order of the search results. > ... > > 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)
While we're on the topic, why in this day and age do we have a custom search? Using google site search would be faster for the user, and more accurate.
I agree. Someone needs to propose a patch though. ...
a custom search in itself is a wonderful thing. To me it also shows more appreciation of visitor concerns than thoses sites, that are just _offering_ google site search (which is accessible anyway to every visitor capable of memorizing the google or bing or whatnot URL).
I second Hernans suggestion about ordering and also his question where the request (and patches) should be directed to. ...
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
On 12/30/2012 1:11 PM, Ezio Melotti wrote:
On Sun, Dec 30, 2012 at 7:54 PM, Hernan Grecco I have seen many people new to Python stumbling while using the Python docs due to the order of the search results.
People should use the index, both on and off line. See the issue below
I experimented with this a bit a while ago. See http://bugs.python.org/issue15871#msg170048.
-- Terry Jan Reedy
On 30Dec2012 18:05, Terry Reedy <tjreedy@udel.edu> wrote: | On 12/30/2012 1:11 PM, Ezio Melotti wrote: | > On Sun, Dec 30, 2012 at 7:54 PM, Hernan Grecco | > I have seen many people new to Python stumbling while using the Python | > docs due to the order of the search results. | | People should use the index, both on and off line. See the issue below Personally, I do. But even that is misleading, or at any rate often not so useful. And since there is a search, its quality should be addressed. IMO the index has similar issues to the search, though on a much smaller scale. You'll see here I'm only offering criticism, no fixes. Cheers, -- Cameron Simpson <cs@zip.com.au> 'Soup: This is the one that Kawasaki sent out pictures, that looks so beautiful. Yanagawa: Yes, everybody says it's beautiful - but many problems! 'Soup: But you are not part of the design team, you're just a test rider. Yanagawa: Yes. I just complain. - _Akira Yanagawa Sounds Off_ @ www.amasuperbike.com
2012/12/30 Hernan Grecco <hernan.grecco@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@python.org http://mail.python.org/mailman/listinfo/python-ideas
+1 I agree it's sub-optimal.
Giampaolo Rodolà <mailto:g.rodola@gmail.com> December 30, 2012 5:38 PM
+1 I agree it's sub-optimal. _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas Hernan Grecco <mailto:hernan.grecco@gmail.com> December 30, 2012 11:54 AM 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@python.org http://mail.python.org/mailman/listinfo/python-ideas
+1 as well, dash has come in handy!
On 31/12/12 04:54, Hernan Grecco wrote:
Hi,
I have seen many people new to Python stumbling while using the Python docs due to the order of the search results. [...] 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.
I'm an experienced person, and I have trouble navigating through the search results. I usually use Google or DuckDuckGo to search, and avoid the website's search functionality altogether. -- Steven
participants (10)
-
Cameron Simpson -
Ezio Melotti -
Georg Brandl -
Giampaolo Rodolà -
Hernan Grecco -
Ned Batchelder -
Ryan Macy -
Stefan Drees -
Steven D'Aprano -
Terry Reedy