classification
Title: Search is not beginner friendly
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Rosuav, ammar2, anthony-flury, docs@python, kamilturek, rhettinger, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2021-03-24 11:12 by anthony-flury, last changed 2021-04-29 16:24 by ammar2.

Pull Requests
URL Status Linked Edit
PR 25045 Rosuav, 2021-03-27 23:57
Messages (4)
msg389442 - (view) Author: Anthony Flury (anthony-flury) * Date: 2021-03-24 11:12
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).
msg389473 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2021-03-24 15:45
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.
msg389627 - (view) Author: Anthony Flury (anthony-flury) * Date: 2021-03-28 01:19
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 ?)
msg392328 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2021-04-29 16:24
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:

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

It would be nice if kwargs/args could also point to that.
History
Date User Action Args
2021-04-29 16:24:39ammar2setnosy: + ammar2
messages: + msg392328
2021-03-28 01:19:55anthony-flurysetmessages: + msg389627
2021-03-27 23:57:28Rosuavsetkeywords: + patch
nosy: + Rosuav

pull_requests: + pull_request23797
stage: patch review
2021-03-24 20:25:41kamiltureksetnosy: + kamilturek
2021-03-24 15:45:44serhiy.storchakasetversions: + Python 3.8, Python 3.10
nosy: + rhettinger, serhiy.storchaka

messages: + msg389473

type: enhancement
2021-03-24 11:12:48anthony-flurycreate