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 <aeros...@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 <songofaca...@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-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?)* <http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-change-the-world/>
_______________________________________________ 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/
