I can't speak for all of the members of the upcoming documentation WG, but as someone that will be on it (based on our discussions at the recent core dev sprint), my personal vote would be for keeping it as a comprehensive guide for beginners of Python. Detailed enough that it covers the fundamentals, but skips out on more advanced topics and info that is likely going to be less applicable to most new users.
I would consider __cause__ and __context__ to fall under the category of being "useful to know, but far from essential for beginners". You can have a decent understanding of most python programs without ever knowing about those two dunders. So I would definitely be in favor of removing the mention of __cause__ and not adding __context__, in my opinion it adds extra unneeded complexity. That being said, I'm not opposed to something like having something like a footnote at the bottom of the section that links to a more advanced topic (maybe an exception how-to?). It should be at the bottom of the section so it doesn't add extra cognitive overhead for those trying to grasp the basics, but allows for those who are interested to get a more in-depth understanding if they want to. I would suggest redirecting the contributor who proposed those changes to working on something like an exception how-to; assuming that's something they're interested in. On Thu, Nov 5, 2020 at 2:07 PM Brett Cannon <br...@python.org> wrote: > A documentation WG is going to be formed which will be in a better > position to answer this, so until that WG is started I think we should keep > the tutorial aimed towards beginners. > > On Thu, Nov 5, 2020 at 1:13 AM Inada Naoki <songofaca...@gmail.com> wrote: > >> Hi, all. >> >> Since "How To" guide is not organized well, it is very tempting to >> write all details in tutorial. >> I have seen may pull requests which "improve" tutorial by describe >> more details and make >> the tutorial more perfect. >> >> But adding more and more information into tutorial makes it slower to >> learn Python by reading tutorial. >> 10+ years ago, Python is far less popular in Japan and reading >> tutorial is the best way to learn Python to me. >> >> But now Python is popular and there are many free/paid good books and >> tutorials on the Web. >> Some of them would be more new user friendly than official tutorial. >> Then, should official Python tutorial become detailed guide to Python? >> Or should we keep new user learning Python as targeted reader? >> >> There is ongoing issue for example: https://bugs.python.org/issue42179 >> >> Chaining exception was added in tutorial. Current tutorial mention to >> `__cause__` attribute. >> https://docs.python.org/3/tutorial/errors.html#exception-chaining >> >> bpo-42179 proposes to add mention to `__context__` to make the >> tutorial more accurate about implicit chaining. >> And https://github.com/python/cpython/pull/23160 is the pull request >> to mention `__context__`. >> >> On the other hand, I want to remove confusion by removing mention to >> `__cause__`. >> Because I don't think `__context__` and `__cause__` is important for new >> users. >> See https://github.com/python/cpython/pull/23162 for my proposal. >> >> Regards, >> >> -- >> Inada Naoki <songofaca...@gmail.com> >> _______________________________________________ >> Python-Dev mailing list -- python-dev@python.org >> To unsubscribe send an email to python-dev-le...@python.org >> https://mail.python.org/mailman3/lists/python-dev.python.org/ >> Message archived at >> https://mail.python.org/archives/list/python-dev@python.org/message/MXMEFFYB6JXAKSS36SZ7DX4ASP6APWFP/ >> Code of Conduct: http://python.org/psf/codeofconduct/ >> > _______________________________________________ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@python.org > https://mail.python.org/mailman3/lists/python-dev.python.org/ > Message archived at > https://mail.python.org/archives/list/python-dev@python.org/message/IWW2YBLJK4T3OWSKDUDVDVXPWDGIFWTC/ > Code of Conduct: http://python.org/psf/codeofconduct/ >
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/FWQWF6BNVILXLYGZ7VVFBWP7OV23URSD/ Code of Conduct: http://python.org/psf/codeofconduct/
