[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Kyle Stanley]

On Sun, Nov 8, 2020 at 8:17 PM Inada Naoki  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.)
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/AF2QAEPVWPSWS6ANXXUHUUMFKR5THPC3/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Kyle Stanley]

 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  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-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/2XKNMFRSK2YUDFDCQFX7XLIHUFQOLTAH/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Guido van Rossum]

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  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  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-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/2XKNMFRSK2YUDFDCQFX7XLIHUFQOLTAH/
> Code of Conduct: http://python.org/psf/codeofconduct/
>


-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/NW34B6OG3PXKEIFDGMV7YZZ7PQZRLM5A/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Simon Cross]

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.
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/GENCYD7WLJTF34LGDC4TN4RXDPN7O2M3/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Chris Angelico]

On Tue, Nov 10, 2020 at 3:19 AM Simon Cross
 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-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/J4P3ACWDJYCQ2MN3KMTR3D76TYHNULKV/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Guido van Rossum]

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  wrote:

> On Tue, Nov 10, 2020 at 3:19 AM Simon Cross
>  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-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/J4P3ACWDJYCQ2MN3KMTR3D76TYHNULKV/
> 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-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/RMOSUNKMORPDOH2WEWUAT2ZWJ6SFC5K3/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Chris Angelico]

On Tue, Nov 10, 2020 at 3:38 AM Guido van Rossum  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
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/HX2XLUBI2MAV5P4NIAIL2VR45KAUHSNQ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Simon Cross]

On Mon, Nov 9, 2020 at 6:38 PM Chris Angelico  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.
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/4LWCOZ7IGFRO67BDUOG2G4FAJW6NTEWH/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Raymond Hettinger]

> On Nov 7, 2020, at 9:51 AM, Riccardo Polignieri via Python-Dev 
>  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-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/CYFDV4ZYGUFGCYUI5HPTF66UNZ4FXO2M/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Mike Miller]

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.

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/ON6LL5LKJQGMYWUAZD3QED2534ZA5VUX/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Pablo Alcain]

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  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  wrote:
>
>> On Tue, Nov 10, 2020 at 3:19 AM Simon Cross
>>  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-le...@python.org
>> https://mail.python.org/mailman3/lists/python-dev.python.org/
>> Message archived at
>> https://mail.python.org/archives/list/python-dev@python.org/message/J4P3ACWDJYCQ2MN3KMTR3D76TYHNULKV/
>> 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-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/RMOSUNKMORPDOH2WEWUAT2ZWJ6SFC5K3/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/WBCISYHODTSCKGN7VAG2YGTSNNJC65HR/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Simon Cross]

+1e6 + 5j # :)
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/YRUHXXBY2AWT7QSXJ5373FYLQPASQVVH/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Zachary Ware]

On Mon, Nov 9, 2020 at 1:29 PM Raymond Hettinger
 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 :)
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/JRHPLRTZDMDMG452DFA7IXCORKLW/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Guido van Rossum]

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.hettin...@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-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/CYFDV4ZYGUFGCYUI5HPTF66UNZ4FXO2M/
> Code of Conduct: http://python.org/psf/codeofconduct/
>


-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/CVH7MDXLAHSECLSZBJTMGRHM2ONYUAPA/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Steven D'Aprano]

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-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/L4AJ6DGLYYSIYKAJYRXO6SL3KPWPQA2Q/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Please do not remove random bits of information from the tutorial

[Carol Willing]

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  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-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/L4AJ6DGLYYSIYKAJYRXO6SL3KPWPQA2Q/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/ZGA4MO57GZO6ONDKLXRG3Z3D3GV7ZABZ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: My thoughts on Pattern Matching.

[Tobias Kohn]

Hi Thomas,

Thank you very much for your carefully worded and thoughtful email.  I  
feel, however, that many of your concerns are based on an idealised  
picture of a future Python language that will never actually  
materialise.


As I understand it your main point is that the concept of patterns  
might---or even should---be retro-fitted to general assignments.  Just  
as we have borrowed from and expanded on the idea of iterable  
unpacking in assignments, so should assignments then pick up the  
concepts introduced in pattern matching.  Indeed, assignments of the  
form ``Viking(spam, ham) = ...`` are not only appealing but can be  
found in various languages with pattern matching.  So, why would we  
not want to have consistent concepts and symmetric (orthogonal)  
structures across all of Python?


Unfortunately, such consistency or symmetry comes at a high cost---too  
high as far as I am concerned.


One of the simplest patterns is without doubt the literal pattern that  
essential only matches itself (e.g., ``case 123:`` or ``case  
'abc':``).  Any future unification of patterns and assignments would  
therefore necessarily allow for statement such as::


    1 = x
    
This is essentially equivalent to ``assert(x == 1)``.  Indeed,  
_Elixir_ [1] uses such syntax for exactly this semantics.  However,  
knowing how much novice programmers struggle with understanding that  
assignments are right-to-left (i.e. ``x = 1`` and not ``1 = x``),  
including such syntax would immediately raise the learning curve  
significantly.  In short, a very common students' mistake will take  
them to error messages and concepts they could not possibly understand  
without a basic comprehension of pattern matching.


And this is probably where it becomes most obvious how our views of  
pattern matching differ.  The pattern matching as we propose it in  
PEPs 634/635/636 is guarded by a keyword needed to activate these  
features.  Unless you start your statement with ``match my_data:``,  
you can easily pretend as if pattern matching did not exist: it will  
not, cannot affect your code.  This encapsulation is intentional and  
by design.


As far as I am aware, those languages that support syntax like  
``Viking(spam, ham) = ...`` only allow this in combination with  
variable _declaration_, i.e. you actually have to write ``let  
Viking(spam, ham) = `` or ``var Viking(spam, ham) = ...`` or similar.   
Without such a marker, this syntax quickly descends into unreadable  
gibberish.  As noted in the original section of rejected ideas in PEP  
622, we had originally considered adding 'one-off pattern matching':  
pattern matching with only a single case that must succeed, very much  
like normal assignments do.  But our approach was always guarded by a  
keyword, be that ``case`` or ``if``---in line with the ``var`` or  
``let`` found in other languages.  Even in that case, patterns would  
not leak into the language outside pattern matching.


Finally, there is already a necessary inconsistency between iterable  
unpacking and pattern matching.  By their very nature, patterns  
express a _possible_ structure, whereas iterable unpacking imposes a  
_necessary_ structure.  So, when dealing with iterators, it is safe to  
'unpack' the iterator in iterable unpacking.  If the expected and  
actual structures differ, it is an error, anyway.  In pattern  
matching, however, we have to be more conservative and careful,  
exploring options rather than certanties.  Hence, even if all other  
concerns were wiped away, the closest we could come to an entirely  
symmetric and consistent language is one with some subtle differences  
and thus prone for bugs and errors.


PEPs 634/635/636 are the result of a long and careful design process  
where we sought to appeal to the intuition of the Python programmer as  
much as possible, without betraying the differences and new concepts  
that pattern matching necessarily introduces.  Readability was always  
one of our main concerns and we believe that having a clear context  
where patterns occur greatly helps writing readable and consistent code.


So, long story short, I am afraid I would question the very premise  
upon which your concerns are founded: that it would ever be a good  
idea to expand patterns to assignments in general.  Although such a  
unification was in principle possible, it would rob Python of one of  
its greatest and strongest assets: its simplicity and learnability.


Kind regards,
Tobias

[1]  https://elixir-lang.org/getting-started/pattern-matching.html

 
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/KOYU2FAY3DZ4EHYWR3FXBQMTDP72EEQQ/
Code of Conduct: http://python.org/psf/codeofconduct/