
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/