Who is target reader of tutorial?
Hi, all. Since "How To" guide is not organized well, it is very tempting to write all details in tutorial. I have seen may pull requests which "improve" tutorial by describe more details and make the tutorial more perfect. But adding more and more information into tutorial makes it slower to learn Python by reading tutorial. 10+ years ago, Python is far less popular in Japan and reading tutorial is the best way to learn Python to me. But now Python is popular and there are many free/paid good books and tutorials on the Web. Some of them would be more new user friendly than official tutorial. Then, should official Python tutorial become detailed guide to Python? Or should we keep new user learning Python as targeted reader? There is ongoing issue for example: https://bugs.python.org/issue42179 Chaining exception was added in tutorial. Current tutorial mention to `__cause__` attribute. https://docs.python.org/3/tutorial/errors.html#exception-chaining bpo-42179 proposes to add mention to `__context__` to make the tutorial more accurate about implicit chaining. And https://github.com/python/cpython/pull/23160 is the pull request to mention `__context__`. On the other hand, I want to remove confusion by removing mention to `__cause__`. Because I don't think `__context__` and `__cause__` is important for new users. See https://github.com/python/cpython/pull/23162 for my proposal. Regards, -- Inada Naoki <songofacandy@gmail.com>
Was reading a tuto by vinay sajip on the official site the other day and i can say that the tutos are great, they just need to be more in numbers. With the old style look of the tutos i dont think as you pointed out that new readers will go through it. better resources exist. I suggest we keep it as well groomed tutos whereby people can know that if i need a good tuto, the py site has some. Beginner infos exist in abundance and quality materials pyramids to the top. I suggest we let masters write more articles, preferring coverage and conciseness over full depth (if someone wants a really detailed tuto, better go to the docs) Kind Regards, Abdur-Rahmaan Janhangeer https://www.github.com/Abdur-RahmaanJ Mauritius sent from gmail client on Android, that's why the signature is so ugly.
IMO, the tutorial should remain as a document aimed at new users, and therefore it definitely should *not* include too much detail. I've helped a couple of friends learn Python and I have always directed them to the tutorial as the "official" guide for new users. If the tutorial is no longer aimed at new users, what should we recommend? I'm not aware of a 3rd party book or tutorial that we'd want to endorse as the "official" one. Paul On Thu, 5 Nov 2020 at 09:19, Inada Naoki <songofacandy@gmail.com> wrote:
Hi, all.
Since "How To" guide is not organized well, it is very tempting to write all details in tutorial. I have seen may pull requests which "improve" tutorial by describe more details and make the tutorial more perfect.
But adding more and more information into tutorial makes it slower to learn Python by reading tutorial. 10+ years ago, Python is far less popular in Japan and reading tutorial is the best way to learn Python to me.
But now Python is popular and there are many free/paid good books and tutorials on the Web. Some of them would be more new user friendly than official tutorial. Then, should official Python tutorial become detailed guide to Python? Or should we keep new user learning Python as targeted reader?
There is ongoing issue for example: https://bugs.python.org/issue42179
Chaining exception was added in tutorial. Current tutorial mention to `__cause__` attribute. https://docs.python.org/3/tutorial/errors.html#exception-chaining
bpo-42179 proposes to add mention to `__context__` to make the tutorial more accurate about implicit chaining. And https://github.com/python/cpython/pull/23160 is the pull request to mention `__context__`.
On the other hand, I want to remove confusion by removing mention to `__cause__`. Because I don't think `__context__` and `__cause__` is important for new users. See https://github.com/python/cpython/pull/23162 for my proposal.
Regards,
-- Inada Naoki <songofacandy@gmail.com> _______________________________________________ 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/MXMEFFYB... Code of Conduct: http://python.org/psf/codeofconduct/
@PaulMoore i see this: There is a list of tutorials suitable for experienced programmers on the BeginnersGuide/Tutorials <http://wiki.python.org/moin/BeginnersGuide/Programmers> page. written here: https://www.python.org/about/gettingstarted/ XD Kind Regards, Abdur-Rahmaan Janhangeer https://www.github.com/Abdur-RahmaanJ Mauritius
A documentation WG is going to be formed which will be in a better position to answer this, so until that WG is started I think we should keep the tutorial aimed towards beginners. On Thu, Nov 5, 2020 at 1:13 AM Inada Naoki <songofacandy@gmail.com> wrote:
Hi, all.
Since "How To" guide is not organized well, it is very tempting to write all details in tutorial. I have seen may pull requests which "improve" tutorial by describe more details and make the tutorial more perfect.
But adding more and more information into tutorial makes it slower to learn Python by reading tutorial. 10+ years ago, Python is far less popular in Japan and reading tutorial is the best way to learn Python to me.
But now Python is popular and there are many free/paid good books and tutorials on the Web. Some of them would be more new user friendly than official tutorial. Then, should official Python tutorial become detailed guide to Python? Or should we keep new user learning Python as targeted reader?
There is ongoing issue for example: https://bugs.python.org/issue42179
Chaining exception was added in tutorial. Current tutorial mention to `__cause__` attribute. https://docs.python.org/3/tutorial/errors.html#exception-chaining
bpo-42179 proposes to add mention to `__context__` to make the tutorial more accurate about implicit chaining. And https://github.com/python/cpython/pull/23160 is the pull request to mention `__context__`.
On the other hand, I want to remove confusion by removing mention to `__cause__`. Because I don't think `__context__` and `__cause__` is important for new users. See https://github.com/python/cpython/pull/23162 for my proposal.
Regards,
-- Inada Naoki <songofacandy@gmail.com> _______________________________________________ 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/MXMEFFYB... Code of Conduct: http://python.org/psf/codeofconduct/
Agreed, I like to refer beginners there who are new to Python but not new to coding. On Thu, Nov 5, 2020 at 11:03 AM Brett Cannon <brett@python.org> wrote:
A documentation WG is going to be formed which will be in a better position to answer this, so until that WG is started I think we should keep the tutorial aimed towards beginners.
On Thu, Nov 5, 2020 at 1:13 AM Inada Naoki <songofacandy@gmail.com> wrote:
Hi, all.
Since "How To" guide is not organized well, it is very tempting to write all details in tutorial. I have seen may pull requests which "improve" tutorial by describe more details and make the tutorial more perfect.
But adding more and more information into tutorial makes it slower to learn Python by reading tutorial. 10+ years ago, Python is far less popular in Japan and reading tutorial is the best way to learn Python to me.
But now Python is popular and there are many free/paid good books and tutorials on the Web. Some of them would be more new user friendly than official tutorial. Then, should official Python tutorial become detailed guide to Python? Or should we keep new user learning Python as targeted reader?
There is ongoing issue for example: https://bugs.python.org/issue42179
Chaining exception was added in tutorial. Current tutorial mention to `__cause__` attribute. https://docs.python.org/3/tutorial/errors.html#exception-chaining
bpo-42179 proposes to add mention to `__context__` to make the tutorial more accurate about implicit chaining. And https://github.com/python/cpython/pull/23160 is the pull request to mention `__context__`.
On the other hand, I want to remove confusion by removing mention to `__cause__`. Because I don't think `__context__` and `__cause__` is important for new users. See https://github.com/python/cpython/pull/23162 for my proposal.
Regards,
-- Inada Naoki <songofacandy@gmail.com> _______________________________________________ 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/MXMEFFYB... Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ 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/IWW2YBLJ... 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 can't speak for all of the members of the upcoming documentation WG, but as someone that will be on it (based on our discussions at the recent core dev sprint), my personal vote would be for keeping it as a comprehensive guide for beginners of Python. Detailed enough that it covers the fundamentals, but skips out on more advanced topics and info that is likely going to be less applicable to most new users. I would consider __cause__ and __context__ to fall under the category of being "useful to know, but far from essential for beginners". You can have a decent understanding of most python programs without ever knowing about those two dunders. So I would definitely be in favor of removing the mention of __cause__ and not adding __context__, in my opinion it adds extra unneeded complexity. That being said, I'm not opposed to something like having something like a footnote at the bottom of the section that links to a more advanced topic (maybe an exception how-to?). It should be at the bottom of the section so it doesn't add extra cognitive overhead for those trying to grasp the basics, but allows for those who are interested to get a more in-depth understanding if they want to. I would suggest redirecting the contributor who proposed those changes to working on something like an exception how-to; assuming that's something they're interested in. On Thu, Nov 5, 2020 at 2:07 PM Brett Cannon <brett@python.org> wrote:
A documentation WG is going to be formed which will be in a better position to answer this, so until that WG is started I think we should keep the tutorial aimed towards beginners.
On Thu, Nov 5, 2020 at 1:13 AM Inada Naoki <songofacandy@gmail.com> wrote:
Hi, all.
Since "How To" guide is not organized well, it is very tempting to write all details in tutorial. I have seen may pull requests which "improve" tutorial by describe more details and make the tutorial more perfect.
But adding more and more information into tutorial makes it slower to learn Python by reading tutorial. 10+ years ago, Python is far less popular in Japan and reading tutorial is the best way to learn Python to me.
But now Python is popular and there are many free/paid good books and tutorials on the Web. Some of them would be more new user friendly than official tutorial. Then, should official Python tutorial become detailed guide to Python? Or should we keep new user learning Python as targeted reader?
There is ongoing issue for example: https://bugs.python.org/issue42179
Chaining exception was added in tutorial. Current tutorial mention to `__cause__` attribute. https://docs.python.org/3/tutorial/errors.html#exception-chaining
bpo-42179 proposes to add mention to `__context__` to make the tutorial more accurate about implicit chaining. And https://github.com/python/cpython/pull/23160 is the pull request to mention `__context__`.
On the other hand, I want to remove confusion by removing mention to `__cause__`. Because I don't think `__context__` and `__cause__` is important for new users. See https://github.com/python/cpython/pull/23162 for my proposal.
Regards,
-- Inada Naoki <songofacandy@gmail.com> _______________________________________________ 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/MXMEFFYB... Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ 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/IWW2YBLJ... Code of Conduct: http://python.org/psf/codeofconduct/
Thanks Inada-san for bringing up this issue. I agree with your point and Guido's that the tutorial should target learning Python if new to the language but not coding. It's likely that in the future there will be an even more basic tutorial for those newer to coding. An advanced concept, as Kyle mentions, is fine when it is a sentence or two and refers back to the in-depth documentation. Care should be taken when introducing an advanced topic or use case to have it at the end of a section and not interleaved with the examples that suit the majority of learners (Python beginners and intermediate developers). On Thu, Nov 5, 2020 at 12:35 PM Kyle Stanley <aeros167@gmail.com> wrote:
I can't speak for all of the members of the upcoming documentation WG, but as someone that will be on it (based on our discussions at the recent core dev sprint), my personal vote would be for keeping it as a comprehensive guide for beginners of Python. Detailed enough that it covers the fundamentals, but skips out on more advanced topics and info that is likely going to be less applicable to most new users.
I would consider __cause__ and __context__ to fall under the category of being "useful to know, but far from essential for beginners". You can have a decent understanding of most python programs without ever knowing about those two dunders. So I would definitely be in favor of removing the mention of __cause__ and not adding __context__, in my opinion it adds extra unneeded complexity.
That being said, I'm not opposed to something like having something like a footnote at the bottom of the section that links to a more advanced topic (maybe an exception how-to?). It should be at the bottom of the section so it doesn't add extra cognitive overhead for those trying to grasp the basics, but allows for those who are interested to get a more in-depth understanding if they want to. I would suggest redirecting the contributor who proposed those changes to working on something like an exception how-to; assuming that's something they're interested in.
On Thu, Nov 5, 2020 at 2:07 PM Brett Cannon <brett@python.org> wrote:
A documentation WG is going to be formed which will be in a better position to answer this, so until that WG is started I think we should keep the tutorial aimed towards beginners.
On Thu, Nov 5, 2020 at 1:13 AM Inada Naoki <songofacandy@gmail.com> wrote:
Hi, all.
Since "How To" guide is not organized well, it is very tempting to write all details in tutorial. I have seen may pull requests which "improve" tutorial by describe more details and make the tutorial more perfect.
But adding more and more information into tutorial makes it slower to learn Python by reading tutorial. 10+ years ago, Python is far less popular in Japan and reading tutorial is the best way to learn Python to me.
But now Python is popular and there are many free/paid good books and tutorials on the Web. Some of them would be more new user friendly than official tutorial. Then, should official Python tutorial become detailed guide to Python? Or should we keep new user learning Python as targeted reader?
There is ongoing issue for example: https://bugs.python.org/issue42179
Chaining exception was added in tutorial. Current tutorial mention to `__cause__` attribute. https://docs.python.org/3/tutorial/errors.html#exception-chaining
bpo-42179 proposes to add mention to `__context__` to make the tutorial more accurate about implicit chaining. And https://github.com/python/cpython/pull/23160 is the pull request to mention `__context__`.
On the other hand, I want to remove confusion by removing mention to `__cause__`. Because I don't think `__context__` and `__cause__` is important for new users. See https://github.com/python/cpython/pull/23162 for my proposal.
Regards,
-- Inada Naoki <songofacandy@gmail.com> _______________________________________________ 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/MXMEFFYB... Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ 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/IWW2YBLJ... Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ 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/FWQWF6BN... Code of Conduct: http://python.org/psf/codeofconduct/
05.11.20 11:12, Inada Naoki пише:
Since "How To" guide is not organized well, it is very tempting to write all details in tutorial. I have seen may pull requests which "improve" tutorial by describe more details and make the tutorial more perfect.
But adding more and more information into tutorial makes it slower to learn Python by reading tutorial. 10+ years ago, Python is far less popular in Japan and reading tutorial is the best way to learn Python to me.
But now Python is popular and there are many free/paid good books and tutorials on the Web. Some of them would be more new user friendly than official tutorial. Then, should official Python tutorial become detailed guide to Python? Or should we keep new user learning Python as targeted reader?
I think the tutorial should be targeted to new Python users, which already know one or more programming languages. It should not be an introduction into programming, nor a detailed guide. I myself learned Python by just reading tutorial. Contained enough information to start coding and to understand some fundamental differences of Python from other programming languages, but not too heavy. Additional details I learned from the library reference. For advanced topics there are "How to" and the language reference. At that time (Python 2.2) it was the best tutorial that I read. Other language tutorials was either too large and formal, or spent several chapters explaining what is bits and loops.
I started to learn Python with the tutorial, and two things come into my mind: 1. The class section seems quite difficult and intimidating for a novel, while classes in Python are really more simple than in other OO languages 2. I really missed a section about how to write a decorator function. Luckily, the web is full of examples. PS I learnt C, C++ and Fortran at university, so I was the "target audience".
It would also be nice for the tutorial to separate between "things you need to know to use Python" vs "things you need to write a Python library". For example, the fact that operators can do different things for different values (e.g. int, str, list, pathlib) would be in the first category, while the details of how to override operators can wait for the second. I see many people suffer from content that goes too deep too quickly, and I'm more and more convinced over time that this is the right place to draw a separator for Python. Many devs are just using the language and never implementing a class (or often, even writing a function). Having a canonical tutorial to get these users through this stage first before going deeper would be great. Cheers, Steve
I agree with you that the tutorial should focus at users, not library developers. But assuming that users will never write a class seems wrong. For example, while ago I went through a PyTorch tutorial, which assumes barely any programming knowledge, and yet the first or second example has the user write a class, as this is apparently the conventional way to store parameters for ML models. --Guido On Fri, Nov 6, 2020 at 8:32 AM Steve Dower <steve.dower@python.org> wrote:
It would also be nice for the tutorial to separate between "things you need to know to use Python" vs "things you need to write a Python library".
For example, the fact that operators can do different things for different values (e.g. int, str, list, pathlib) would be in the first category, while the details of how to override operators can wait for the second.
I see many people suffer from content that goes too deep too quickly, and I'm more and more convinced over time that this is the right place to draw a separator for Python. Many devs are just using the language and never implementing a class (or often, even writing a function). Having a canonical tutorial to get these users through this stage first before going deeper would be great.
Cheers, 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/E7Y5MB4J... 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...>
Hopefully that was a dataclass :) But yes, point taken. Classes need to be there. And now I've gone and re-read the table of contents for the tutorial, I really don't have any complaints about the high-level ordering. It does seem to go unnecessarily deep in some areas (*very* few people will ever need position-only parameters, for example, and I'd say all special parameters matter more in the tutorial because of how you _call_ them, rather than how you define them). Cheers, Steve On 06Nov2020 1714, Guido van Rossum wrote:
I agree with you that the tutorial should focus at users, not library developers. But assuming that users will never write a class seems wrong. For example, while ago I went through a PyTorch tutorial, which assumes barely any programming knowledge, and yet the first or second example has the user write a class, as this is apparently the conventional way to store parameters for ML models.
--Guido
On Fri, Nov 6, 2020 at 8:32 AM Steve Dower <steve.dower@python.org <mailto:steve.dower@python.org>> wrote:
It would also be nice for the tutorial to separate between "things you need to know to use Python" vs "things you need to write a Python library".
For example, the fact that operators can do different things for different values (e.g. int, str, list, pathlib) would be in the first category, while the details of how to override operators can wait for the second.
I see many people suffer from content that goes too deep too quickly, and I'm more and more convinced over time that this is the right place to draw a separator for Python. Many devs are just using the language and never implementing a class (or often, even writing a function). Having a canonical tutorial to get these users through this stage first before going deeper would be great.
Cheers, Steve
@MarcoSulla You started from the tutorials? you are a real legend 💯 great people were already great before they became great it seems ~ Kind Regards, Abdur-Rahmaan Janhangeer https://www.github.com/Abdur-RahmaanJ Mauritius sent from gmail client on Android, that's why the signature is so ugly.
On 11/6/20 9:07 AM, Marco Sulla wrote:
I started to learn Python with the tutorial, and two things come into my mind: 1. The class section seems quite difficult and intimidating for a novel, while classes in Python are really more simple than in other OO languages
Indeed - we got some complaints about the class chapter at the webmaster@python.org alias a while back. The introductory section repeatedly mentions Modula-3 and Smalltalk, languages which more recently minted programmers aren't very likely to be familiar with, which makes it a bit of a daunting beginning - this is the one chapter that could really use a bit of rework, IMO.
Ouch, that's bad. It seems the class tutorial could use an overhaul. We might also cut a few areas where we go unnecessarily deep (e.g. position-only parameters). On Fri, Nov 6, 2020 at 9:31 AM Mats Wichmann <mats@wichmann.us> wrote:
On 11/6/20 9:07 AM, Marco Sulla wrote:
I started to learn Python with the tutorial, and two things come into my mind: 1. The class section seems quite difficult and intimidating for a novel, while classes in Python are really more simple than in other OO languages
Indeed - we got some complaints about the class chapter at the webmaster@python.org alias a while back. The introductory section repeatedly mentions Modula-3 and Smalltalk, languages which more recently minted programmers aren't very likely to be familiar with, which makes it a bit of a daunting beginning - this is the one chapter that could really use a bit of rework, IMO.
_______________________________________________ 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/B54VI2DN... 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...>
As I remember the webmaster@ discussions, Mats did go so far as to start a re-write of the classes section, but it never got as far as a PR. Kind regards, Steve On Fri, Nov 6, 2020 at 5:51 PM Guido van Rossum <guido@python.org> wrote:
Ouch, that's bad. It seems the class tutorial could use an overhaul.
We might also cut a few areas where we go unnecessarily deep (e.g. position-only parameters).
On Fri, Nov 6, 2020 at 9:31 AM Mats Wichmann <mats@wichmann.us> wrote:
On 11/6/20 9:07 AM, Marco Sulla wrote:
I started to learn Python with the tutorial, and two things come into my mind: 1. The class section seems quite difficult and intimidating for a novel, while classes in Python are really more simple than in other OO languages
Indeed - we got some complaints about the class chapter at the webmaster@python.org alias a while back. The introductory section repeatedly mentions Modula-3 and Smalltalk, languages which more recently minted programmers aren't very likely to be familiar with, which makes it a bit of a daunting beginning - this is the one chapter that could really use a bit of rework, IMO.
_______________________________________________ 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/B54VI2DN... 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...> _______________________________________________ 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/QRWFPASA... Code of Conduct: http://python.org/psf/codeofconduct/
participants (12)
-
Abdur-Rahmaan Janhangeer -
Brett Cannon -
Carol Willing -
Guido van Rossum -
Inada Naoki -
Kyle Stanley -
Marco Sulla -
Mats Wichmann -
Paul Moore -
Serhiy Storchaka -
Steve Dower -
Steve Holden