[New-bugs-announce] [issue43614] Search is not beginner friendly

[Anthony Flury]

New submission from Anthony Flury <anthony.flury at btinternet.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 at python
components: Documentation
messages: 389442
nosy: anthony-flury, docs at python
priority: normal
severity: normal
status: open
title: Search is not beginner friendly
versions: Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue43614>
_______________________________________