New submission from Sydney Pemberton <spember...@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@python components: Documentation files: Confusing docs.ipynb messages: 371690 nosy: Sydney Pemberton, docs@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 <rep...@bugs.python.org> <https://bugs.python.org/issue40994> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
