[issue37134] [EASY] Use PEP570 syntax in the documentation

[Raymond Hettinger]

Raymond Hettinger <raymond.hettinger at gmail.com> added the comment:

> If you think me pushing for this change will impact somehow
> our ability to work together I will close the PR and the issue. 

Not at all.  I always enjoy working with you and appreciate the depth of thinking you bring to every task :-)

Here, we just disagree on whether changing the docs will be a net aid or net detriment to end users.  My belief is that the docs will be less usable, less intuitive, and less approachable.  People using the docs are already alone and in need of help.  Cryptic notation doesn't make this task easier.  While a person can be trained to read this notation, it is my belief that a person shouldn't have to have training to read the docs.

Unlike other decisions where predicting the future is uncertain, we already have some user testing results because the \ notation was exposed in help() via the argument clinic.  The results have not been favorable.  AFAICT not one single user has benefitted from seeing something like this output from help(len):

    len(obj, /)
        Return the number of items in a container.

The / is a stumbling block. My unscientific twitter poll had mostly WTF reactions from end-users. This wasn't limited to beginners -- Steve Holden and David Beazley have both found this notation detrimental to communication.

This week I joined a twitter thread where I needed to defend the existing docs.  The contention was that docs aren't very usable for end-users and that the existing core devs lacked writing skills and were too interested in technical details rather than plain communication. (I mostly disagree with this, but there is another core dev consistently giving this message in talks all around the world).  The essential point here is that there are already usability concerns with the documentation.  My belief is that this PR will make the situation worse.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37134>
_______________________________________