Raymond Hettinger <[email protected]> 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 <[email protected]>
<https://bugs.python.org/issue37134>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
