I think when Riccardo said "The PEPs are the worst," he meant that PEPs
do not work well as documentation for features, because it was not their
purpose. PEPs are designed to be proposals, and then summaries of
decisions. I agree with him that linking to PEPs should be for
supporting information about the rationale of a feature; they should
only be used as the documentation of a feature as a last resort.
--Ned.
On 11/12/20 3:45 PM, Guido van Rossum wrote:
The correct place for the docs for __cause__ and __context__ is in the
section in the library reference about exceptions. There's quite a bit
about them there already. That's where the tutorial should link as well.
And now I ask you to stop complaining (your "the PEPs are the worst"
does not help your cause).
On Thu, Nov 12, 2020 at 12:30 PM Riccardo Polignieri via Python-Dev
<python-dev@python.org <mailto:python-dev@python.org>> wrote:
> There is value in having non-trivial coverage of the language.
When people ask how
> __cause__ works, we can link to the tutorial.
I don't necessarily agree with the rest, but I think this is very
important - at least, in the
current situation. Maybe in the future we will be able to
rearrange and move some parts
of the tutorial into the "how to" section, and/or to write more
introductions to the various
sections of the documentation... but for now, the tutorial is all
we have.
> Otherwise, we have to throw them to the
> wolves by linking to the unfriendly, highly technical reference
guide or to a PEP.
Indeed. The PEPs are the worst, more often than not. I remember
when I first learned Pyhton,
every time the documentation linked to a PEP, I felt a shiver down
my spine.
r.
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
<mailto:python-dev@python.org>
To unsubscribe send an email to python-dev-le...@python.org
<mailto:python-dev-le...@python.org>
https://mail.python.org/mailman3/lists/python-dev.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/LHGZNTRKU2Z2OD3W7DPFEDS274OBFE7F/
<https://mail.python.org/archives/list/python-dev@python.org/message/LHGZNTRKU2Z2OD3W7DPFEDS274OBFE7F/>
Code of Conduct: http://python.org/psf/codeofconduct/
<http://python.org/psf/codeofconduct/>
--
--Guido van Rossum (python.org/~guido <http://python.org/~guido>)
/Pronouns: he/him //(why is my pronoun here?)/
<http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-change-the-world/>
_______________________________________________
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/ILOS6URJIPNVV7XKBVPUR6FYEBVLZGIZ/
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/KUZNJ6ZGPI2U6NWA6K7CE6WFI2VEULIT/
Code of Conduct: http://python.org/psf/codeofconduct/
