[New-bugs-announce] [issue40994] Very confusing documenation for abc.Collections

[Sydney Pemberton]

New submission from Sydney Pemberton <spemberton at auntbertha.com>:

I was writing a Jupyter notebook at the time, which I think perfectly illustrated the blind alley this documentation bug led me down before beating me up and stealing my lunch money.

I have come to this point in the documentation at least half a dozen times while learning Python and always left confused and with the sense that Python is more complicated than I had thought. 

Notebook attached. 

This documentation style violates two principles:
 - The implied structure of headings and content below it.
 - Many natural languages do not contain context-sensitive grammar and so using the "respectively" idiom can be very confusing for people who speak English as a second language.

----------
assignee: docs at python
components: Documentation
files: Confusing docs.ipynb
messages: 371690
nosy: Sydney Pemberton, docs at python
priority: normal
severity: normal
status: open
title: Very confusing documenation for abc.Collections
versions: Python 3.8
Added file: https://bugs.python.org/file49238/Confusing docs.ipynb

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