New submission from Anthony Flury email@example.com:
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).
---------- assignee: docs@python components: Documentation messages: 389442 nosy: anthony-flury, docs@python priority: normal severity: normal status: open title: Search is not beginner friendly versions: Python 3.9
Serhiy Storchaka firstname.lastname@example.org added the comment:
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.
---------- nosy: +rhettinger, serhiy.storchaka type: -> enhancement versions: +Python 3.10, Python 3.8
Change by Chris Angelico email@example.com:
---------- keywords: +patch nosy: +Rosuav nosy_count: 5.0 -> 6.0 pull_requests: +23797 stage: -> patch review pull_request: https://github.com/python/cpython/pull/25045
Anthony Flury firstname.lastname@example.org added the comment:
Is PR 25045 the correct Pull request - this Issue is a documentation change - the linked PR is related to Issue 43433 (a change to xmlrpc.client ?)
Ammar Askar email@example.com added the comment:
Just a little update to this, now that issue34398 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:
It would be nice if kwargs/args could also point to that.
---------- nosy: +ammar2