New submission from Matt <excala...@tutanota.com>:
* Problem: Documentation search results favor tutorials and over language specifications * How to reproduce: I often forget simple syntax. For example, say I want to raise an exception. Clearly, I need to search for "raise". 1. Go to https://docs.python.org/3.6/search.html 2. Type in "raise" * Expected result: A clearly understandable link to the "raise" documentation or something closely related, such as link to the "Built-in Exceptions" documentation * Actual result: The documentation for the "raise" keyword is given in search result number... at first, second, and third glance, I don't even know if a page describing the "raise" command is returned. The first result is a 2to3 conversion tutorial. The second result is for urllib.error. The third result is a unittest.mock tutorial The fourth result is an optparse tutorial The fifth result is a tutorial for "simple statements" The sixth result is a tutorial for "Errors and exceptions". The seventh result is a for "exception handling" After much poking around, it turns out that the documentation for "raise" is in the "Simple statements" tutorial. Knowing to select the correct link requires knowing that "raise" is a statement, as the only indication that this is the correct link is that "raise_stmt" occurs in its preview snippet. Searching for related terms, such as "exceptions" or "errors", returns similarly indirect results, such as tutorials for "Extending Python with C or C++" and "API Reference". The experience is the same, regardless of the Python version searched. * Proposed solution: I'm not sure how I can help with this, but I would like to. For example, is there some kind of tagging I could do while meandering through the morass of Python documentation? ---------- assignee: docs@python components: Documentation messages: 352846 nosy: docs@python, excalamus priority: normal severity: normal status: open title: Documentation search results focus on tutorials and not language specifications type: behavior versions: Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue38231> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
