Search is not beginner friendly

[TonyFlury]

BPO	43614
Nosy	@rhettinger, @Rosuav, @serhiy-storchaka, @ammaraskar, @TonyFlury, @kamilturek
PRs	bpo-43433: Reattach query parameters after parsing URI #25045

^{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 = None
created_at = <Date 2021-03-24.11:12:48.698>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Search is not beginner friendly'
updated_at = <Date 2021-04-29.16:24:39.303>
user = 'https://github.com/TonyFlury'

bugs.python.org fields:

activity = <Date 2021-04-29.16:24:39.303>
actor = 'ammar2'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-03-24.11:12:48.698>
creator = 'anthony-flury'
dependencies = []
files = []
hgrepos = []
issue_num = 43614
keywords = ['patch']
message_count = 4.0
messages = ['389442', '389473', '389627', '392328']
nosy_count = 7.0
nosy_names = ['rhettinger', 'docs@python', 'Rosuav', 'serhiy.storchaka', 'ammar2', 'anthony-flury', 'kamilturek']
pr_nums = ['25045']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue43614'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[TonyFlury]

A commonly asked question on Quora is 'What do *args and **kwargs' mean ?

While it is relatively easy for community to answer these questions the search tool on the standard documentation doesn't make it easy.

I understand that 'args' and 'kwargs' are both naming conventions, they are very common across the documentation, but searching on '*args' or '**kwargs' doesn't actually find anything useful - it certainly doesn't place 'https://docs.python.org/3/tutorial/controlflow.html#arbitrary-argument-lists' at or close to the top of the list.

It is my view that the documentation should be beginner friendly, but in this case (and many other I guess) you have to know what to search for to find something useful.

I note that even common phrases in Computing (such as 'variable arguments' or 'variable parameters') don't find anything useful. The term 'variadic' does find the relevant page, but the link displayed in the search results lands on the page (but not the relevant section) - and many beginners wont search for 'variadic'.

The index and search need to be improved to help beginners - specifically in this case

• Search Index should include common conventional names (such as args, kwargs)
• Search Index should include common computing terms ('variable arguments' for example - even if the documentation doesn't actually use that terminology).
• Search should link to the relevant section (and not just the page).

[serhiy-storchaka]

Ha! I just was going to open the same issue (perhaps we read the same post on Quora).

I concur that it is perhaps worth to add index entries for common parameter names (args, kwargs, self, cls) and also for *args and **kwargs and add notions that such name is commonly used for such parameter.

[TonyFlury]

Is PR 25045 the correct Pull request - this Issue is a documentation change - the linked PR is related to bpo-43433 (a change to xmlrpc.client ?)

[ammaraskar]

Just a little update to this, now that bpo-34398 is fixed it is possible to make this more beginner friendly by making sure the right terms have glossary entries.

As an example, here is a search for "argument" on the latest docs:

https://docs.python.org/3.10/search.html?q=argument

It would be nice if kwargs/args could also point to that.

[CAM-Gerlach]

Related: #60075 and #89541

If this just involves adding glossary entries for some common terms, I can try to take a look at this soon-ish, since this is high-impact but should be fairly straightforward to accomplish.

We should compile a list of relevant entries to add. Here are those mentioned here:

• args
• kwargs
• self
• cls
• dunder?
• walrus (operator)?

I'm there there are others; one thing I believe Guido mentioned elsewhere was * and / in signatures, though I'll have to see if they'll actually work as glossary entries.

[serhiy-storchaka]

No, I do not think that we need glossary entries for these words. There are already entries for var-positional and var-keyword parameters. We need to make search for args and kwargs finding these entries.

It would be nice if search work for Python operators and other syntax elements that are present in the index: +, **, """.

[CAM-Gerlach]

No, I do not think that we need glossary entries for these words. There are already entries for var-positional and var-keyword parameters. We need to make search for args and kwargs finding these entries.

Ah, good point, thanks—we wouldn't want to duplicate that then, just make it easier to find, since the peculiar terms "var-positional" and "var-keyword" for these aren't used anywhere else I could find in the docs, nor in general usage (such that I missed them myself).

While we could just add stub terms that point back to the main term as is done for positional and keyword argument, this requires readers to jump an extra step, and still doesn't point to the specific part of the parameter entry it refers to (which is the longest in the glossary and takes up a full screen when searching), which may lead to confusion and ambiguity. Likewise, we could just add multiple terms to the same existing entry, but this would overload the term list and doesn't fix the main problems (length and ambiguity).

Instead, we should split the bullets for positional-only, keyword-only, positional variadic and keyword variadic parameters into their own entries that have their respective aliases as additional terms, and cross-linking the main entry to the sub-entries and vice versa. Then, searching for kwargs, *args or keyword-only argument will resolve to the specific term and display just the relevant text, while searching for parameter won't display a wall of text in the results. We will need to fix the custom glossary search code to properly handle multi-term entries as it should, but that should be doable. I can open a PR once I get one merged to fix another issue with the same code in #90492 .

That does leave self and cls, and potentially others, unresolved:

• Method does mention self, but I'm not sure it makes sense as a (visible) alias and there currently isn't a way I know of to make an invisible one, so it would have to be a separate entry
• cls isn't mentioned anywhere at all, so it would have to be a new entry

It would be nice if search work for Python operators and other syntax elements that are present in the index: +, **, """.

See sphinx-doc/sphinx#6692 ; @AA-Turner is working on it for Sphinx 5.2.0 🎉