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 <aeros167@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 <songofacandy@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-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/2XKNMFRS... 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...>