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 <songofacandy@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  <songofacandy@gmail.com>
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@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-leave@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/