[Python-Dev] Re: Please do not remove random bits of information from the tutorial
Hi Inada, > Note that the discussion not only in the b.p.o thread, but in this > mailing list too. > Please read this long thread. I have, but I don't know if I want to step in... I do have, indeed, opinions (and some expertise) on the matter, but I've never really thought about it in depth... In short, I believe that the tutorial was originally intended for the beginners... except, the very definition of "beginner" has shifted a lot in the meantime, as the audience of Python users widened. This poses difficulties that in my opinion could be solved only by rewriting the tutorial from scratch, or maybe by adding a new one to the existing one. In any case, I think that any changes to the tutorial should not be done in the same way as the rest of the documentation, but ideally only through an editorial, centralized, process. In the meantime, I would insist that any changes should be made very carefully, especially when we delete something. > For the record, when I removed the __cause__ from the tutorial, I > believe I was careful and conservative enough. > I think from exc syntax is not new Python users should know. > Documenting implicit chaining is enough for 99% use cases, and from > None covers 0.99% of the rest. As I said, I have no strong opinion on this particular case. Rather, I am slightly concerned about the method in itself - that a deletion may occur following only a brief exchange on the bug tracker. For what it's worth, however, I would have kept the passing mention on __cause__, and would have added a passing mention on __context__ too. It's not what I would write today in a tutorial for the "modern" beginner, but it's certainly more *consistent* with what the tutorial is right now. > So I considered removing explicit chaining (e.g. from exc) from the > section too. See... this is what really concerns me. At some point someone may decide out of the blue to remove an entire important concept from the tutorial because "it's just noise for a beginner". Now in this case thankfully the article in the documentation does a good job of explaining exception chaining in plain language (that's not a good reason not to keep at least one mention in the tutorial as well, however). But very often the documentation is very terse and the tutorial is the only place where some concepts are presented in a discursive way ... even if not "beginner friendly". All in all, although I understand that the tutorial should be completely revised, I would still recommend the utmost caution especially when deleting information. best, riccardo ___ 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/67SOABAYWY3J47RE2DEHOG7MNBCRGGPD/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Please do not remove random bits of information from the tutorial
On Mon, Nov 9, 2020 at 3:46 AM Riccardo Polignieri via Python-Dev wrote: > > Hi Inada, > > > Note that the discussion not only in the b.p.o thread, but in this > > mailing list too. > > Please read this long thread. > > I have, but I don't know if I want to step in... > I do have, indeed, opinions (and some expertise) on the matter, but > I've never really thought about it in depth... > Then, you know the deletion is after long discussion, not only short discussion in b.p.o. > > In any case, I think that any changes to the tutorial should not be done > in the same way as the rest of the documentation, but ideally only > through an editorial, centralized, process. > Agree. Tutorial should be written in special care. When editing library or language references, editors can focus one section and technical correctness. On the other hand, when editing tutorials, editors should read the whole chapter and understand story. And keep in mind that new Python users may learn Python by reading tutorial always. > In the meantime, I would insist that any changes should be made > very carefully, Agree. > especially when we delete something. > Can't agree. Same care is required for adding something too. > > For the record, when I removed the __cause__ from the tutorial, I > > believe I was careful and conservative enough. > > I think from exc syntax is not new Python users should know. > > Documenting implicit chaining is enough for 99% use cases, and from > > None covers 0.99% of the rest. > > As I said, I have no strong opinion on this particular case. > Rather, I am slightly concerned about the method in itself - that a deletion > may occur following only a brief exchange on the bug tracker. > Again, I did it following not only a brief exchange on the b.p.o., but also long discussion in Python-dev. > For what it's worth, however, I would have kept the passing mention on > __cause__, and would have added a passing mention on __context__ too. > It's not what I would write today in a tutorial for the "modern" beginner, > but it's certainly more *consistent* with what the tutorial is right now. I don't think so. I agree that the tutorial is "syntax showcase" for now. Many minor or expert syntaxes are described. But the tutorial isn't a "special attribute showcase". It doesn't cover all special attributes and describe how Python interpreter use the special attributes under the ground. So removing __cause__ made the tutorial more consistent right now. > > > So I considered removing explicit chaining (e.g. from exc) from the > > section too. > > See... this is what really concerns me. At some point someone may decide > out of the blue to remove an entire important concept from the tutorial > because "it's just noise for a beginner". You are ignoring me! I said I considered removing "explicit" chaining (e.g. `from exc`). But I said "implicit chaining is enough for 99% use cases". Definitely, I never tried to "remove an entire important concept from the tutorial." > But very often the documentation is very terse and the tutorial is the only > place > where some concepts are presented in a discursive way ... even if not > "beginner friendly". > You know, exception chaining is described well in other place so it was removed. I promise that I don't remove something in the tutorial without checking it is described well in other places. Regards, -- Inada Naoki ___ 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/B55E5SWJ5XZZ6LOTA4VG76MAYMJ3DMO7/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Please do not remove random bits of information from the tutorial
On 11/8/2020 5:51 PM, Inada Naoki wrote: On Mon, Nov 9, 2020 at 3:46 AM Riccardo Polignieri via Python-Dev wrote: Rather, I am slightly concerned about the method in itself - that a deletion may occur following only a brief exchange on the bug tracker. Again, I did it following not only a brief exchange on the b.p.o., but also long discussion in Python-dev. When I act on an issue on the basis of a pydev discussion, I hopefully remember to avoid such after-the-fact concerns by mentioning the thread with a title and brief summary. Example: "In pydev thread '', 3 of 4 coredevs agreed with this change." (Made up numbers do not refer to any particular issue.) FWIW, I agreed with this particular change also. > exception chaining is described well in other place If on the ball, I would have mentioned this also, and where. -- Terry Jan Reedy ___ 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/SEVFT4NXFQ3547HZVYZRRBEWNR4TPONL/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Please do not remove random bits of information from the tutorial
On Mon, Nov 9, 2020 at 9:20 AM Terry Reedy wrote: > > > > > Again, I did it following not only a brief exchange on the b.p.o., but > > also long discussion in Python-dev. > > When I act on an issue on the basis of a pydev discussion, I hopefully > remember to avoid such after-the-fact concerns by mentioning the thread > with a title and brief summary. Example: "In pydev thread '', 3 of > 4 coredevs agreed with this change." (Made up numbers do not refer to > any particular issue.) FWIW, I agreed with this particular change also. > OK. Since checking all mails in the long thread is tedious job, I will pick some up and leave a comment in the b.p.o. > > exception chaining is described well in other place > > If on the ball, I would have mentioned this also, and where. > https://docs.python.org/3/library/exceptions.html#built-in-exceptions This is mentioned from the reviced tutorial, python-dev thread, and b.p.o issue. Regards, -- Inada Naoki ___ 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/VRWGDZWUGHELGO77AANXQSA6G4ROPXZO/ Code of Conduct: http://python.org/psf/codeofconduct/
