IMO, the tutorial should remain as a document aimed at new users, and therefore it definitely should *not* include too much detail.
I've helped a couple of friends learn Python and I have always directed them to the tutorial as the "official" guide for new users. If the tutorial is no longer aimed at new users, what should we recommend? I'm not aware of a 3rd party book or tutorial that we'd want to endorse as the "official" one. Paul On Thu, 5 Nov 2020 at 09:19, 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/6D5WSTGB7X7BRLXZSJNT3YPGNZW7U75R/ Code of Conduct: http://python.org/psf/codeofconduct/
