
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-leave@python.org <mailto:python-dev-leave@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/LHGZNTRK... <https://mail.python.org/archives/list/python-dev@python.org/message/LHGZNTRK...> 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-c...>
_______________________________________________ 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/ILOS6URJ... Code of Conduct: http://python.org/psf/codeofconduct/