Repository navigation
Documentation search results focus on tutorials and not language specifications #82412
Description
| BPO | 38231 |
|---|---|
| Nosy | @terryjreedy, @ammaraskar, @excalamus |
| Superseder |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = <Date 2019-09-21.01:37:37.142>
created_at = <Date 2019-09-20.13:39:39.503>
labels = ['3.8', 'type-bug', '3.7', '3.9', 'docs']
title = 'Documentation search results focus on tutorials and not language specifications'
updated_at = <Date 2019-09-21.01:37:37.141>
user = 'https://github.com/excalamus'bugs.python.org fields:
activity = <Date 2019-09-21.01:37:37.141>
actor = 'ammar2'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-09-21.01:37:37.142>
closer = 'ammar2'
components = ['Documentation']
creation = <Date 2019-09-20.13:39:39.503>
creator = 'excalamus'
dependencies = []
files = []
hgrepos = []
issue_num = 38231
keywords = []
message_count = 5.0
messages = ['352846', '352864', '352867', '352868', '352917']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'docs@python', 'ammar2', 'excalamus']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '34398'
type = 'behavior'
url = 'https://bugs.python.org/issue38231'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9']
Activity
excalamus commentedon Sep 20, 2019
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".
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.
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?
ammaraskar commentedon Sep 20, 2019
This is a great point Matt, the documentation search is a bit lacking and we're kind of using https://bugs.python.org/issue34398 and #8773 to track it.
The current idea that Julien, the docs expert, had is to add some sort of Sphinx directive in the docs that boosts and entry's search result. Would you like to close this issue in favor of that one...or post your comment there so we can track these in one place?
excalamus commentedon Sep 20, 2019
I will close this issue and post in one of the two places you linked.
Thank you for your prompt reply and affirmation of my observations. I feel my language was colored by frustration, yet you focused instead on my willingness to help. I appreciate that and find your response encouraging.
Somewhat related, I am responding to this through the bugs.python.org interface. If I reply directly to the email the tracker sent me, will my reply be properly routed to this thread? It's not clear from the send address what would happen if I replied via email.
ammaraskar commentedon Sep 20, 2019
Yes, it will :)
The bug tracker allows replies by email.
terryjreedy commentedon Sep 21, 2019
But in your response, please delete the message you are responding to (except possibly a line or two).