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-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 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/LCS2QQIGCJUOJ2JH664Y3CXXRPV5E5XA/
Code of Conduct: http://python.org/psf/codeofconduct/
