This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author Dominik V.
Recipients Dominik V., docs@python, rhettinger
Date 2020-04-20.22:10:25
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1587420625.52.0.0477608048705.issue40344@roundup.psfhosted.org>
In-reply-to
Content
It was not my intention to disturb the traffic on the bug tracker. My apologies if that caused any trouble. I also thought only people subscribed to the indicated topic (e.g. "Documentation") would receive a notification.

The docs pages mention that for enhancement proposals one should submit a bug report on the tracker:

> If you find a bug in this documentation or would like to propose an improvement, please submit a bug report on the tracker (https://docs.python.org/3/bugs.html).

I do care about the quality of Python's documentation and I think it could be improved in these cases. Often it is newcomers who consult these pages and they might be irritated by the mentioned parts.

I see how it would be distracting to include a more complex real world example, but using an example which performs apparently superfluous steps without any additional comment might seem strange. More experienced users probably won't need such an example at all. In addition it might make people falsely belief that `str.join` expects a list of strings rather than any iterable, and hence the explicit construction of the list.
History
Date User Action Args
2020-04-20 22:10:25Dominik V.setrecipients: + Dominik V., rhettinger, docs@python
2020-04-20 22:10:25Dominik V.setmessageid: <1587420625.52.0.0477608048705.issue40344@roundup.psfhosted.org>
2020-04-20 22:10:25Dominik V.linkissue40344 messages
2020-04-20 22:10:25Dominik V.create