TBH (perhaps just my personal opinion), very few PEPs have written this section well, but also very few have really needed to. We also haven’t strongly encouraged this section until relatively recently, so PEPs older than 3-4 years usually won’t have much at all.
There’s a much higher expectation on a new syntax construct that isn’t simply an extension of something that already exists. e.g. I think PEP 614 (arbitrary decorators) is too brief, but only by a couple of paragraphs, while PEP 636 (the pattern matching tutorial) is right for the scale of that feature.
At a minimum, I think this one ought to cover:
- how will the code reader/reviewer who’s never seen this syntax before recognise that something unusual is happening
- what’s the one-line explanation a teacher could give for what is happening here
- what prior knowledge is required to understand that one-line explanation
- what prior assumptions are invalidated by learning about this feature[1]
- what’s the “casual name” for the feature (we’re fairly against calling things “PEP 736 syntax”)
- is it reasonable to believe that a learner will absorb the concept[2] after having it explained, and why
And given all that: “was it worth the effort?” Which is really a question for the PEP delegate to answer, based on the discussion and consensus that forms as we discuss it here.
This is probably the hardest question of the lot, but I’ll point out that invalidating a past assumption is often a good thing. This case might be “I thought I had to type everything that I meant or the compiler wouldn’t know about it, but it turns out I was wrong!” ↩︎
Or if you prefer, “build a mental model for how it works” or “integrate it into their existing mental model of Python” ↩︎