[issue43614] Search is not beginner friendly

[Ammar Askar]

Ammar Askar  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:

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

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

--
nosy: +ammar2

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43614] Search is not beginner friendly

[Anthony Flury]

Anthony Flury  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 ?)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43614] Search is not beginner friendly

[Chris Angelico]

Change by Chris Angelico :


--
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

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43614] Search is not beginner friendly

[Kamil Turek]

Change by Kamil Turek :


--
nosy: +kamilturek

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43614] Search is not beginner friendly

[Serhiy Storchaka]

Serhiy Storchaka  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

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue43614] Search is not beginner friendly

[Anthony Flury]

New submission from Anthony Flury :

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

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com