[Python-Dev] Please do not remove random bits of information from the tutorial
Dear all, I am the maintainer of an Italian translation of the Python Tutorial: https://pytutorial-it.readthedocs.io. Since the Italian translation is kept in sync with the original repo (across all the branches!), from time to time I get an alert when a change is committed. This morning I noticed this new commit, referring to bpo-42179: "Remove mention of __cause__" (https://bugs.python.org/issue42179). From reading this thread, it turns out that a minor confusion in the wording, about __cause__ and __context__, very quickly turned into the decision to completely remove any reference to __cause__, the reason being that "generally speaking (...) we should *reduce* some details from tutorial". While I have no particular opinion on this specific case, I would strongly urge you not to remove random bits of information from the tutorial, even when a link to a specific article is handy. We all know that the tutorial is "too difficult", not really suitable for beginners (perhaps not even Python beginners!). Having spent a couple of weeks translating it as recently as this spring, I am well aware of this. At times, it feels more like a demo or a features' showcase: a feeling reinforced, by the way, often by the *recent* additions like the special parameters syntax (https://docs.python.org/3/tutorial/controlflow.html#special-parameters). However, unless someone undertakes a sweeping rewriting of the tutorial (and until they do), I think it would be unwise to start cherry-picking the occasional bit of information to expunge or "simplify" from time to time, without an overall guideline. Reason is, right now the tutorial is packed with informations (beginner-unfriendly as they might be) that you would be hard pressed to find elsewhere in the documentation: see the aforementioned section on special parameters; see the maddening chapter on Classes (and especially the exposition on scopes and namespaces); see, of course, the floating point appendix; and I could go on. My concern here is that if you start removing or simplifying some "too-difficult-for-a-tutorial" bits of information on an occasional basis, and without too much scrutiny or editorial guidance, you will end up loosing something precious. Like everyone, I also look forward to an overall rewriting of the tutorial; but in the meantime, I would kindly ask you to be very careful and conservative about deleting information solely for "didactic" reasons. thanks a lot riccardo polignieri ___ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/WNHVZLEO3ZVDOFP2FHRBUQR4GY24RIJJ/ Code of Conduct: http://python.org/psf/codeofconduct/
[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 -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/67SOABAYWY3J47RE2DEHOG7MNBCRGGPD/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Please do not remove random bits of information from the tutorial
Inada, as I said before, mine was more a general consideration than a criticism of a particular change (let alone a particular committer!). > 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. Eh... as you know very well, at some point the tutorial lists *all* the methods of a list... and at another point, when presenting "sys" in the standard library tour, the really important thing it feels the need to say is that we have "sys.ps1" and "sys.ps2" to customize the prompt... and at another point, while dealing with the very simple task of telling us what is a docstring, it is keen to explain also how a docstring parser tool should work... So, let's just say that there are quite a few quirks in the tutorial, and establishing what is "consistent" is anyone's guess, ok? > 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." Look, we are really trading in hypotheticals here, because no one has actually deleted anything important at the end of the day... But for the sake of the argument, I venture that it might be slightly more complicated than expected to draw a line and say what is enough for 99% use cases, in a language as widely used as Python. This is not to say that I wouldn't gloss over exception chaining myself... if I were writing a tutorial for beginners. And I would certainly advocate for such a document to be added to the Python documentation, at some point in the future. My point, however, is that the document we have right now is *not* this tutorial, and yet it can still be of use to many people (who may or may not be "beginners"), just as it is now. And, that if you start removing things, on the one hand you are not doing beginners a favor big enough, while you might be damaging (even if only scratching) something useful for others. best, r. ___ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/BDB4KXCSW2QKSISI7JN2XTKI73UKVBJF/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Please do not remove random bits of information from the tutorial
Hi Kyle, > ... I think that we should use the > guideline of: "Is this useful information in 95% of real-world use cases or > does it have a strong niche purpose that will be useful at some point for > significant number of Python users?" If not, my opinion is that it should > be removed ... I'm afraid it might be just a little more complicated than expected to draw such a line. Of course "metaclasses are deeper magic than 99% of users should ever worry about" (and we don't have those in the tutorial indeed), but I would argue that 95% of python code out there makes use of 50-60% of what is now covered in the tutorial. (And 95% of code *by beginners* wouldn't reach the 30% threshold.) > There shouldn't be a concern that we'll be "removing random bits of > information from the tutorial", (...) > I would personally wait until having 3+ opinions prior to merging any > removals (...) Thanks for this. Besides, I can see from the Git log that the tutorial is indeed seldom updated anyway, which is a pity on the one hand, a relief on the other. best, riccardo ___ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/IYLSHHNY3ZSWCWYAEUAQ2AGLJHGTFFLT/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Please do not remove random bits of information from the tutorial
> I suspect that future documentation will have "How Tos" being more often > written to cover more technical topics in detail. These more standalone > "How Tos" can then be linked to from contents and search pages. Indeed. Take for instance the most recent addition, regarding special parameters syntax. Now the entire section 4.7 has become long and complex, way beyond the limits of a beginner's tolerance. But a well-calibrated "functions parameters how to" could be an excellent remedy, even leading to the removal of this entire section from the tutorial. Now, this would be a deletion that I would welcome. I suspect there are quite a few (relatively) low hanging fruits like this one out there. best, riccardo ___ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/7S4W65OJQPIN66IY5NRNMQ6NZJ4T36R4/ Code of Conduct: http://python.org/psf/codeofconduct/
[Python-Dev] Re: Please do not remove random bits of information from the tutorial
> 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 -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/LHGZNTRKU2Z2OD3W7DPFEDS274OBFE7F/ Code of Conduct: http://python.org/psf/codeofconduct/
