[issue40994] Very confusing documenation for abc.Collections
Sydney Pemberton added the comment: Yes, that would be great. I will figure out how to do that shortly. On Fri, Aug 14, 2020 at 3:23 AM Irit Katriel wrote: > > Irit Katriel added the comment: > > Sydney, do you want to create a PR for this? I'm happy to if you don't. > > -- > > ___ > Python tracker > <https://bugs.python.org/issue40994> > _______ > -- Sydney Pemberton Software Engineer 512.740.6591 spember...@auntbertha.com Aunt Bertha <https://company.auntbertha.com/> | The Social Care Network -- ___ Python tracker <https://bugs.python.org/issue40994> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40994] Very confusing documenation for abc.Collections
Sydney Pemberton added the comment: Nothing to do with Jupyter itself. When I'm reading the documentation I don't necessarily think that a sibling "node" in the document structure is going to have anything to do with my current section. So it was weird to see the section entirely empty. Also, I'm not saying that all non-native speakers are going to be unfamiliar with the construction, but it is certainly more widely understandable if the definitions are kept separate. On Thu, Aug 13, 2020 at 12:54 PM Irit Katriel wrote: > > Irit Katriel added the comment: > > Sydney, is the issue related to how Jupyter notebook displays the > documentation? > > -- > > ___ > Python tracker > <https://bugs.python.org/issue40994> > _______ > -- Sydney Pemberton Software Engineer 512.740.6591 spember...@auntbertha.com Aunt Bertha <https://company.auntbertha.com/> | The Social Care Network -- ___ Python tracker <https://bugs.python.org/issue40994> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40994] Very confusing documenation for abc.Collections
Sydney Pemberton added the comment: If you look at the Jupyter notebook it should be fairly clear but to summarize here is the issue: class collections.abc.Container class collections.abc.Hashable class collections.abc.Sized class collections.abc.Callable ABCs for classes that provide respectively the methods __contains__(), __hash__(), __len__(), and __call__(). This should become class collections.abc.Container ABC for classes that provide the method __contains__(). class collections.abc.Hashable ABC for classes that provide the method __hash__(). class collections.abc.Sized ABC for classes that provide the method __len()__. class collections.abc.Callable ABC for classes that provide the method __call__(). -- ___ Python tracker <https://bugs.python.org/issue40994> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40994] Very confusing documenation for abc.Collections
New submission from Sydney Pemberton : 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 <https://bugs.python.org/issue40994> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
