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
Hi, Riccardo. I'm who removed the __cause__ from tutorial, and I had translated Japanese translation of official Python document hard. On Sun, Nov 8, 2020 at 3:07 AM Riccardo Polignieri via Python-Dev <python-dev@python.org> wrote:
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".
Note that the discussion not only in the b.p.o thread, but in this mailing list too. Please read this long thread. https://mail.python.org/archives/list/python-dev@python.org/thread/MXMEFFYB6...
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).
Agree.
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.
I expect documenting working group will discuss the 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.
Agree. There are tons of beginner unfriendly bits in the tutorial.
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.
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. So I considered removing explicit chaining (e.g. `from exc`) from the section too. But I kept it, because it's a "syntax showcase" even though it will give more noise to beginners. And deleting `__cause__` is not solery for "didactic" reason, nor "loosing something precious." As written in the b.p.o. issue, mention only `__cause__` "lose some precious". We need to describe `__context__` and `__suppress_context__` too. But all of them are documented in library/exceptions.html. Removing `__cause__` and adding a link to library/exceptions.html makes sense more than documenting all. Bests, -- Inada Naoki <songofacandy@gmail.com>
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
On Mon, Nov 9, 2020 at 3:46 AM Riccardo Polignieri via Python-Dev <python-dev@python.org> 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 <songofacandy@gmail.com>
On 11/8/2020 5:51 PM, Inada Naoki wrote:
On Mon, Nov 9, 2020 at 3:46 AM Riccardo Polignieri via Python-Dev <python-dev@python.org> 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 'xxxx', 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
On Mon, Nov 9, 2020 at 9:20 AM Terry Reedy <tjreedy@udel.edu> 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 'xxxx', 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 <songofacandy@gmail.com>
On Sun, Nov 8, 2020 at 8:17 PM Inada Naoki <songofacandy@gmail.com> wrote:
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.
Personally, I think that just linking to the python-dev thread in bpo (and/or PR) is adequate for most cases, especially if there was a fairly strong consensus pointing in one direction. (More detail can be helpful of course, but if one can only spare enough time to just place a link on the issue, it does quite a lot by itself IMO.)
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.
Rather than trying to specifically transform the existing tutorial into a guide exclusively aimed at beginners, 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 and replaced with a footnote link for more information (if the existing documentation is too technical, we can have it linked to a separate HOWTO which explains it in a way that's easier to parse). On Sat, Nov 7, 2020 at 9:16 PM Inada Naoki <songofacandy@gmail.com> wrote:
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. So I considered removing explicit chaining (e.g. `from exc`) from the section too. But I kept it, because it's a "syntax showcase" even though it will give more noise to beginners.
And deleting `__cause__` is not solery for "didactic" reason, nor "loosing something precious." As written in the b.p.o. issue, mention only `__cause__` "lose some precious". We need to describe `__context__` and `__suppress_context__` too. But all of them are documented in library/exceptions.html. Removing `__cause__` and adding a link to library/exceptions.html makes sense more than documenting all.
So, I think that in a case where as Inada mentioned above, it's not going to be needed for 99% of use cases, my opinion is that the extra information is just consuming valuable real estate in the tutorial that adds a higher burden to readers trying to learn Python for little gain. I'm less concerned about removing parts that are "too difficult" and more concerned with removing parts that are never realistically going to be useful for the vast majority of users (outside of something like implementing the internals of some ultra-niche library). __cause__ is a great example of this, but I would be hesitant to remove explicit chaining; that would require much more consideration because it has a significantly better chance of being relevant for users or at least appearing in code at some point without specifically trying to find it. So I agree with keeping the explicit exception chaining part. There shouldn't be a concern that we'll be "removing random bits of information from the tutorial", any change to the tutorial will be made intentionally and with much consideration. Also, even as a core dev that has spent a decent amount of time reviewing CPython documentation PRs, I would personally wait until having 3+ opinions prior to merging any removals of information or other substantial changes in the tutorial (with at least one other core dev, preferably two), and encourage others to do the same since the tutorial is a very fundamental part of the docs.
It looks like the tutorial has already evolved into something close to a user manual (with a strong narrative component). This definitely sounds like something for the docs workgroup! On Mon, Nov 9, 2020 at 2:02 AM Kyle Stanley <aeros167@gmail.com> wrote:
Rather than trying to specifically transform the existing tutorial into a guide exclusively aimed at beginners, 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 and replaced with a footnote link for more information (if the existing documentation is too technical, we can have it linked to a separate HOWTO which explains it in a way that's easier to parse).
On Sat, Nov 7, 2020 at 9:16 PM Inada Naoki <songofacandy@gmail.com> wrote:
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. So I considered removing explicit chaining (e.g. `from exc`) from the section too. But I kept it, because it's a "syntax showcase" even though it will give more noise to beginners.
And deleting `__cause__` is not solery for "didactic" reason, nor "loosing something precious." As written in the b.p.o. issue, mention only `__cause__` "lose some precious". We need to describe `__context__` and `__suppress_context__` too. But all of them are documented in library/exceptions.html. Removing `__cause__` and adding a link to library/exceptions.html makes sense more than documenting all.
So, I think that in a case where as Inada mentioned above, it's not going to be needed for 99% of use cases, my opinion is that the extra information is just consuming valuable real estate in the tutorial that adds a higher burden to readers trying to learn Python for little gain. I'm less concerned about removing parts that are "too difficult" and more concerned with removing parts that are never realistically going to be useful for the vast majority of users (outside of something like implementing the internals of some ultra-niche library).
__cause__ is a great example of this, but I would be hesitant to remove explicit chaining; that would require much more consideration because it has a significantly better chance of being relevant for users or at least appearing in code at some point without specifically trying to find it. So I agree with keeping the explicit exception chaining part.
There shouldn't be a concern that we'll be "removing random bits of information from the tutorial", any change to the tutorial will be made intentionally and with much consideration. Also, even as a core dev that has spent a decent amount of time reviewing CPython documentation PRs, I would personally wait until having 3+ opinions prior to merging any removals of information or other substantial changes in the tutorial (with at least one other core dev, preferably two), and encourage others to do the same since the tutorial is a very fundamental part of the docs. _______________________________________________ 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/2XKNMFRS... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (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...>
I really enjoyed learning from this "user manual with a strong narrative component" so I would personally like to see it stay even if a new tutorial is created for a different kind of audience.
On Tue, Nov 10, 2020 at 3:19 AM Simon Cross <hodgestar+pythondev@gmail.com> wrote:
I really enjoyed learning from this "user manual with a strong narrative component" so I would personally like to see it stay even if a new tutorial is created for a different kind of audience.
If that were to happen, what I'd prefer is to cut lots of info out of the *TUTORIAL* and make a new document called, say, *Python Advanced Techniques* or something, which could still have the narrative style but would be aimed at people who know how to use basic functionality and are looking to learn more. The name "tutorial" definitely screams "thing you should go through first". It shouldn't have to teach you everything. Keep the tutorial simple. ChrisA
Do you want to join the docs WG? IIUC it’s open to new members. (Carol?) On Mon, Nov 9, 2020 at 08:34 Chris Angelico <rosuav@gmail.com> wrote:
On Tue, Nov 10, 2020 at 3:19 AM Simon Cross <hodgestar+pythondev@gmail.com> wrote:
I really enjoyed learning from this "user manual with a strong narrative component" so I would personally like to see it stay even if a new tutorial is created for a different kind of audience.
If that were to happen, what I'd prefer is to cut lots of info out of the *TUTORIAL* and make a new document called, say, *Python Advanced Techniques* or something, which could still have the narrative style but would be aimed at people who know how to use basic functionality and are looking to learn more.
The name "tutorial" definitely screams "thing you should go through first". It shouldn't have to teach you everything. Keep the tutorial simple.
ChrisA _______________________________________________ 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/J4P3ACWD... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido (mobile)
On Tue, Nov 10, 2020 at 3:38 AM Guido van Rossum <guido@python.org> wrote:
Do you want to join the docs WG? IIUC it’s open to new members. (Carol?)
Me personally, or members of this conversation in general? My life is a bit too chaotic at the moment to take on more responsibilities, although I might reconsider in mid 2021. But don't let that stop anyone else who's interested. ChrisA
for what it's worth, i would really like to be part of the docs workgroup. if anyone confirms it's open, count me in! On Mon, Nov 9, 2020 at 1:38 PM Guido van Rossum <guido@python.org> wrote:
Do you want to join the docs WG? IIUC it’s open to new members. (Carol?)
On Mon, Nov 9, 2020 at 08:34 Chris Angelico <rosuav@gmail.com> wrote:
On Tue, Nov 10, 2020 at 3:19 AM Simon Cross <hodgestar+pythondev@gmail.com> wrote:
I really enjoyed learning from this "user manual with a strong narrative component" so I would personally like to see it stay even if a new tutorial is created for a different kind of audience.
If that were to happen, what I'd prefer is to cut lots of info out of the *TUTORIAL* and make a new document called, say, *Python Advanced Techniques* or something, which could still have the narrative style but would be aimed at people who know how to use basic functionality and are looking to learn more.
The name "tutorial" definitely screams "thing you should go through first". It shouldn't have to teach you everything. Keep the tutorial simple.
ChrisA _______________________________________________ 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/J4P3ACWD... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido (mobile) _______________________________________________ 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/RMOSUNKM... Code of Conduct: http://python.org/psf/codeofconduct/
On Mon, Nov 9, 2020 at 6:38 PM Chris Angelico <rosuav@gmail.com> wrote:
The name "tutorial" definitely screams "thing you should go through first". It shouldn't have to teach you everything. Keep the tutorial simple.
That's quite subjective. Personally I prefer a more complete tutorial which explains many details so that I don't immediately run into fundamentals I don't understand when I start using what I've learned. K&R was very popular, so I don't think I'm alone in this.
On 2020-11-09 10:44, Simon Cross wrote:
That's quite subjective. Personally I prefer a more complete tutorial which explains many details so that I don't immediately run into fundamentals I don't understand when I start using what I've learned. K&R was very popular, so I don't think I'm alone in this.
Indeed. A common problem with a lot of platform documentation I've experienced is that tutorials are "fluff" for absolute beginners, complemented with terse, dense reference material for experts. There is too often very little in-between to get you to the intermediate level. That's why the current tutorial is fantastic, imho. It doesn't skip the all-important middle part of the journey, and gets you to near-intermediate within a few hours if you've programed before. Perhaps the first step is too high, however. How about a new Section 0: Absolute beginners guide, for those new to programming? -Mike P.S. I didn't see an obvious link to the tutorial from the home page, it is sorta buried under getting-started. Perhaps it could be better highlighted.
On 11/9/20 12:46 PM, Mike Miller wrote:
On 2020-11-09 10:44, Simon Cross wrote:
That's quite subjective. Personally I prefer a more complete tutorial which explains many details so that I don't immediately run into fundamentals I don't understand when I start using what I've learned. K&R was very popular, so I don't think I'm alone in this.
Indeed. A common problem with a lot of platform documentation I've experienced is that tutorials are "fluff" for absolute beginners, complemented with terse, dense reference material for experts. There is too often very little in-between to get you to the intermediate level.
That's why the current tutorial is fantastic, imho. It doesn't skip the all-important middle part of the journey, and gets you to near-intermediate within a few hours if you've programed before.
Perhaps the first step is too high, however. How about a new Section 0: Absolute beginners guide, for those new to programming?
Just 2 cents' worth, the difficulty this discussion exposes is things In The Wrong Place (subjective), and maybe not all of the required places actually complete. I thought the following was a pretty good discussion of the overall problem of documenting a complex ecosystem: https://documentation.divio.com/ If people think that model is reasonable, we sort of have most of it - we have Reference; HowTos and Explanations (mixed together in https://docs.python.org/3/howto/index.html); and Tutorial. _Some_ people think the tutorial has too much stuff that belongs in the HowTos and Explanations buckets, and that's probably where things should be built up. e.g. @raymondh has been working on the Descriptor Howto, which is a good example of more detailed material not getting stuffed in the tutorial :)
On Tue, Nov 10, 2020 at 8:07 AM Mats Wichmann <mats@python.org> wrote:
On 11/9/20 12:46 PM, Mike Miller wrote:
On 2020-11-09 10:44, Simon Cross wrote:
That's quite subjective. Personally I prefer a more complete tutorial which explains many details so that I don't immediately run into fundamentals I don't understand when I start using what I've learned. K&R was very popular, so I don't think I'm alone in this.
Indeed. A common problem with a lot of platform documentation I've experienced is that tutorials are "fluff" for absolute beginners, complemented with terse, dense reference material for experts. There is too often very little in-between to get you to the intermediate level.
That's why the current tutorial is fantastic, imho. It doesn't skip the all-important middle part of the journey, and gets you to near-intermediate within a few hours if you've programed before.
Perhaps the first step is too high, however. How about a new Section 0: Absolute beginners guide, for those new to programming?
Just 2 cents' worth, the difficulty this discussion exposes is things In The Wrong Place (subjective), and maybe not all of the required places actually complete. I thought the following was a pretty good discussion of the overall problem of documenting a complex ecosystem:
Daniele Procido who is involved with Divio has shared this with us when we were planning a workgroup. It's excellent content and guidelines.
If people think that model is reasonable, we sort of have most of it - we have Reference; HowTos and Explanations (mixed together in https://docs.python.org/3/howto/index.html); and Tutorial. _Some_ people think the tutorial has too much stuff that belongs in the HowTos and Explanations buckets, and that's probably where things should be built up. e.g. @raymondh has been working on the Descriptor Howto, which is a good example of more detailed material not getting stuffed in the tutorial :)
I agree. I wouldn't suggest a major refactor of the existing tutorial right now (next 1-2 years). Instead, new beginner tutorial pages targeted at user groups (primary school students, scientists, web developers, etc.) would make sense to supplement the existing 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.
_______________________________________________ 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/GBPCAGDX... Code of Conduct: http://python.org/psf/codeofconduct/
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
On Tue, Nov 10, 2020 at 03:33:06AM +1100, Chris Angelico wrote:
If that were to happen, what I'd prefer is to cut lots of info out of the *TUTORIAL* and make a new document called, say, *Python Advanced Techniques* or something, which could still have the narrative style but would be aimed at people who know how to use basic functionality and are looking to learn more.
I think that there is a lot of middle ground between "simple" stuff for beginners and "advanced techniques" for experts. Is it too much to expect beginners to skim over parts of the tutorial that are marked as "intermediate" or "expert" level? Personally I find it very helpful to "peek ahead" to get an idea of the material ahead, and see how the current material fits into the broader picture. What do we mean by "beginners"? Who is the tutorial aimed at? Eg: - self-taught 12 year olds passionate about learning to program - surly 15 year old students being forced to learn Python for school - scientists needing to learn to interact with scientific libraries, but with no interest in programming beyond the barest minimum they need to make the libraries work - sys admins with 20 years experience in other languages looking to get an introduction to Python so they can be productive etc. All of the above?
The name "tutorial" definitely screams "thing you should go through first".
Not to me. When I was at uni, the tutorial was the thing you went through *second*, after the main lectures, to reinforce what you had already learned from the lecturers and text book. When I tutor students professionally, I teach them new material, oh, maybe one time in twenty. The rest of the time we're covering material they have already learned.
It shouldn't have to teach you everything.
Then it's a good thing it doesn't attempt to :-) -- Steve
We'll be making an announcement in a few weeks asking folks to apply for the workgroup. The workgroup will be at most 20 people with the goal of having significant representation (25% to 50%) of individuals who are educators and documentarians. One goal of the workgroup is to set documentation priorities for new documentation and act as an editorial board for existing documentation. In addition to the workgroup, we'll be booting up a Documentation Team which will be open to all. The plan is to hold open monthly meetings (alternating times to accommodate folks globally). We'll be setting up something similar to how we have run JupyterHub and Binder meetings for the past few years: https://github.com/jupyterhub/team-compass The hope is that folks will feel a sense of community around documentation. On Mon, Nov 9, 2020 at 6:34 PM Steven D'Aprano <steve@pearwood.info> wrote:
On Tue, Nov 10, 2020 at 03:33:06AM +1100, Chris Angelico wrote:
If that were to happen, what I'd prefer is to cut lots of info out of the *TUTORIAL* and make a new document called, say, *Python Advanced Techniques* or something, which could still have the narrative style but would be aimed at people who know how to use basic functionality and are looking to learn more.
I think that there is a lot of middle ground between "simple" stuff for beginners and "advanced techniques" for experts.
Is it too much to expect beginners to skim over parts of the tutorial that are marked as "intermediate" or "expert" level? Personally I find it very helpful to "peek ahead" to get an idea of the material ahead, and see how the current material fits into the broader picture.
What do we mean by "beginners"? Who is the tutorial aimed at? Eg:
- self-taught 12 year olds passionate about learning to program
- surly 15 year old students being forced to learn Python for school
- scientists needing to learn to interact with scientific libraries, but with no interest in programming beyond the barest minimum they need to make the libraries work
- sys admins with 20 years experience in other languages looking to get an introduction to Python so they can be productive
etc. All of the above?
The name "tutorial" definitely screams "thing you should go through first".
Not to me.
When I was at uni, the tutorial was the thing you went through *second*, after the main lectures, to reinforce what you had already learned from the lecturers and text book.
When I tutor students professionally, I teach them new material, oh, maybe one time in twenty. The rest of the time we're covering material they have already learned.
It shouldn't have to teach you everything.
Then it's a good thing it doesn't attempt to :-)
-- Steve _______________________________________________ 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/L4AJ6DGL... Code of Conduct: http://python.org/psf/codeofconduct/
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
On Nov 7, 2020, at 9:51 AM, Riccardo Polignieri via Python-Dev <python-dev@python.org> wrote:
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.
I concur with you sentiments and do not want the tutorial to be dumbed down. Here are a few thoughts on the subject: * The word "tutorial" does not imply "easy". Instead it is a self-paced, example driven walk-through of the language. That said, if the word "tutorial" doesn't sit well, then just rename the guide. * The world is full of well-written guides for beginners. The variety is especially important because "beginner" means many different things: "never programmed before", "casually checking out what the language offers", "expert in some other language", "is a student in elementary school", "is a student in high school", "is an electrical engineer needing write scripts", etc. * One thing that makes the current tutorial special is that much of it was written by Guido. Delete this text and you lose one of the few places where his voice comes through. * There is value in having non-trivial coverage of the language. When people ask how __cause__ works, we can link to the tutorial. Otherwise, we have to throw them to the wolves by linking to the unfriendly, highly technical reference guide or to a PEP. * For many people, our tutorial serves as the only systematic walk-through of the language. If you decide to drop the mention of complex numbers, the odds of a person ever finding about that capability drop to almost zero. * My suggestion is that we add a section to the beginning of the tutorial with external links elsewhere, "If you are ten years old, go here. If have never programmed before, go here, etc" * If you think the word tutorial implies fluffy and easy, then let's just rename it to "Language walk-through with examples" or some such. * FWIW, I've closely monitored the bug tracker daily for almost two decades. We almost never get a user complaint that the tutorial is too advanced. For the most part, it has long been of good service to users. Almost certainly it can be improved, but hopefully not be dropping content. Raymond
On Mon, Nov 9, 2020 at 1:29 PM Raymond Hettinger <raymond.hettinger@gmail.com> wrote:
* FWIW, I've closely monitored the bug tracker daily for almost two decades. We almost never get a user complaint that the tutorial is too advanced. For the most part, it has long been of good service to users. Almost certainly it can be improved, but hopefully not be dropping content.
If someone finds the tutorial to be too complex to follow, what is the most likely thing for them to search for: "easy python tutorial", "how do I report that the python tutorial is too hard", or "javascript tutorial"? :) I'd be willing to bet that a large majority of people who have found our tutorial to be too hard have never made a bug tracker account or even sent a message to docs@, and a significant fraction of those have likely never learned Python at all. I don't think there is much that should be *removed* from the current tutorial. However, I do think that the tutorial has grown long and complex enough over the years that there's ample opportunity to trim the main narrative down, and move more advanced topics (and/or more advanced details of basic topics) into an "advanced" section, with good linking between the main and advanced sections. This is one of the many things that the Doc WG should consider. Disclaimer FTR, I did learn Python from the tutorial about a decade ago with very little prior programming experience. It's been about that long since I've actually read through the whole thing, though :)
The current version tutorial *already* isn't written in my voice any more. I don't want to argue about the rest but I disagree with a lot of your other bullets too. On Mon, Nov 9, 2020 at 11:28 AM Raymond Hettinger < raymond.hettinger@gmail.com> wrote:
On Nov 7, 2020, at 9:51 AM, Riccardo Polignieri via Python-Dev < python-dev@python.org> wrote:
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.
I concur with you sentiments and do not want the tutorial to be dumbed down.
Here are a few thoughts on the subject:
* The word "tutorial" does not imply "easy". Instead it is a self-paced, example driven walk-through of the language. That said, if the word "tutorial" doesn't sit well, then just rename the guide.
* The world is full of well-written guides for beginners. The variety is especially important because "beginner" means many different things: "never programmed before", "casually checking out what the language offers", "expert in some other language", "is a student in elementary school", "is a student in high school", "is an electrical engineer needing write scripts", etc.
* One thing that makes the current tutorial special is that much of it was written by Guido. Delete this text and you lose one of the few places where his voice comes through.
* There is value in having non-trivial coverage of the language. When people ask how __cause__ works, we can link to the tutorial. Otherwise, we have to throw them to the wolves by linking to the unfriendly, highly technical reference guide or to a PEP.
* For many people, our tutorial serves as the only systematic walk-through of the language. If you decide to drop the mention of complex numbers, the odds of a person ever finding about that capability drop to almost zero.
* My suggestion is that we add a section to the beginning of the tutorial with external links elsewhere, "If you are ten years old, go here. If have never programmed before, go here, etc"
* If you think the word tutorial implies fluffy and easy, then let's just rename it to "Language walk-through with examples" or some such.
* FWIW, I've closely monitored the bug tracker daily for almost two decades. We almost never get a user complaint that the tutorial is too advanced. For the most part, it has long been of good service to users. Almost certainly it can be improved, but hopefully not be dropping content.
Raymond _______________________________________________ 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/CYFDV4ZY... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (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...>
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.
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> 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 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/LHGZNTRK... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (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...>
On Thu, Nov 12, 2020 at 8:49 PM Guido van Rossum <guido@python.org> 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> wrote:
There is value in having non-trivial coverage of the language. When people ask how __cause__ works, we can link to the tutorial. [...]
A Google search here for python tutorial __cause__ returns as its first hit https://docs.python.org/3/library/exceptions.html (the very section to which it seems you refer). There is a terse but adequate description of __cause there__. It seems unhelpful that the permalink for __cause__ ( https://docs.python.org/3/library/traceback.html?highlight=__cause__#traceba...) links back to itself, but that's the nature of the beast with nested exceptions -- it's __cause__s and __context__s all the way down. A search for __cause__ using the documentations search feature leads to the same loop of links noted above. In either case, if the curious reader follows the traceback_exception link ( https://docs.python.org/3/library/traceback.html?highlight=__cause__#traceba...) they are moved up five lines whereupon the context becomes more obvious.Those who find it intimidating may be a little out of their depth, as this is hardly beginner material. The tutorial was not mentioned in the docs search and the third hit in my Google search, linking to https://docs.python.org/3/tutorial/errors.html. Somewhat ironically, __cause__ is not mentioned on that page.
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/
On 11/9/20 2:25 PM, Raymond Hettinger wrote:
On Nov 7, 2020, at 9:51 AM, Riccardo Polignieri via Python-Dev <python-dev@python.org> wrote:
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. I concur with you sentiments and do not want the tutorial to be dumbed down.
I feel like we are missing a key element of Riccardo's point: "without editorial guidance." Changes are being made without first having an agreement about what the tutorial should be. Personally, I would rather the tutorial did not try to cover everything. If something is only useful to 10% of the readers, I'd prefer to cover it elsewhere. Adding tutorial-style content throughout the rest of the reference documentation seems a fine solution to me. As an example, I tried to use ContextVars for the first time the other day, and would have welcomed a description on their page about how they might be used, where they are useful, and so on.
Here are a few thoughts on the subject:
* The word "tutorial" does not imply "easy". Instead it is a self-paced, example driven walk-through of the language. That said, if the word "tutorial" doesn't sit well, then just rename the guide.
* The world is full of well-written guides for beginners. The variety is especially important because "beginner" means many different things: "never programmed before", "casually checking out what the language offers", "expert in some other language", "is a student in elementary school", "is a student in high school", "is an electrical engineer needing write scripts", etc.
* One thing that makes the current tutorial special is that much of it was written by Guido. Delete this text and you lose one of the few places where his voice comes through.
* There is value in having non-trivial coverage of the language. When people ask how __cause__ works, we can link to the tutorial. Otherwise, we have to throw them to the wolves by linking to the unfriendly, highly technical reference guide or to a PEP.
Linking to content is a great use-case. There's no need for __cause__ to be covered in a linear front-to-back tutorial just so we can link to it. When someone asks how __cause__ works, we could link to the (not yet written) walkthrough about __cause__ elsewhere.
* For many people, our tutorial serves as the only systematic walk-through of the language. If you decide to drop the mention of complex numbers, the odds of a person ever finding about that capability drop to almost zero.
As a compromise, we could include full text for the 80% features in the tutorial, and in each section, include links to "other topics" or "advanced features" in other sections. This would leave the front-to-back readers of the tutorial with a good 80% overview of the language, but also let readers find the tangents that are of interest to them. This is the sort of overall design of the tutorial we should be undertaking.
* My suggestion is that we add a section to the beginning of the tutorial with external links elsewhere, "If you are ten years old, go here. If have never programmed before, go here, etc"
* If you think the word tutorial implies fluffy and easy, then let's just rename it to "Language walk-through with examples" or some such.
* FWIW, I've closely monitored the bug tracker daily for almost two decades. We almost never get a user complaint that the tutorial is too advanced. For the most part, it has long been of good service to users. Almost certainly it can be improved, but hopefully not be dropping content.
Bug reports on bpo are a really bad way to gauge how the tutorial is working for people. Most people looking for a "tutorial" are not going to think to write bug reports like you are expecting, much less find bpo, or go to the trouble of creating an account to write one. --Ned.
Raymond _______________________________________________ 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/CYFDV4ZY... Code of Conduct: http://python.org/psf/codeofconduct/
Ned Batchelder writes:
I feel like we are missing a key element of Riccardo's point: "without editorial guidance." Changes are being made without first having an agreement about what the tutorial should be.
That's really unfortunate. But there also ought to be an editorial activity, such as a "tutorial-SIG" within the docs working group (ie, informality within informality -- IMO the most formal this should get is a mailing list/discuss channel, and maybe a tracker tag) to have some visibility into whether changes serve those purposes.
Personally, I would rather the tutorial did not try to cover everything. If something is only useful to 10% of the readers, I'd prefer to cover it elsewhere.
I'd raise that 10%, maybe as high as 50%. Or maybe that's the wrong dimension to measure, and we should aim for a tutorial that covers enough for 50% of the readers to write a program that gives them more utility than just amusement and a feeling of accomplishment. > Adding tutorial-style content throughout the rest of the reference > documentation seems a fine solution to me. That's fine if the user knows what to look for, but is it really discoverable? In general, I would think that tutorial material should be most easily discoverable on its own, and that the tutorial should link to the reference material, and the reference should link, rather than include, that tutorial. And should "tutorial" material in a reference really go beyond short examples of typical use cases? Maybe these purposes would be be better served by domain-specifici HOWTOs. Eg, HOWTO write a mail filter using the mailbox and email modules. HOWTO write a web spider using requests and aiohttp.
As a compromise, we could include full text for the 80% features in the tutorial, and in each section, include links to "other topics" or "advanced features" in other sections. This would leave the front-to-back readers of the tutorial with a good 80% overview of the language, but also let readers find the tangents that are of interest to them.
I don't know if I agree with this specific outline, but I'm definitely in agreement with the principle that we should be guided by improving discoverability.
participants (17)
-
Carol Willing -
Chris Angelico -
Guido van Rossum -
Inada Naoki -
Kyle Stanley -
Mats Wichmann -
Mike Miller -
Ned Batchelder -
Pablo Alcain -
Raymond Hettinger -
Riccardo Polignieri -
Simon Cross -
Stephen J. Turnbull -
Steve Holden -
Steven D'Aprano -
Terry Reedy -
Zachary Ware