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

[Raymond Hettinger]

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

I respectfully disagree with logic, "the language now permits this, so we should change all the docs to display it everywhere".  That moves it from optional knowledge to mandatory knowledge, from a day ten lesson to a day one lesson, from "once in a while, a user may benefit from being able to mark arguments as positional-only" to the category of "every single user will see this every time they see the docs".  There is a huge difference.

My almost daily experience with end-users regarding the \ annotation has been decidedly negative.  And my experience as a professional tech writer teaches that "people will just have to figure it out" is not a phrase to live by when it comes to documentation (it is an anti-pattern).

There is no reason that we have to do this to the docs.  Please at least go with Carol's suggestion to defer all the trailing \ annotations for at least another release so that you can get more user feedback.

I know some regard The Zen of Python as just poetry, but the "readability counts" and "beautiful is better than ugly" parts mean something.  Those key attractors to the language should not be discarded lightly.

And while a blog post might be nice, the odds are that fewer than 1% of Python users will ever see it.  Python has millions of users and blog posts are rarely seen by more than tens of thousands.  Even then, blog post knowledge is transient and quickly becomes yesterday's news.  The entire notion of training away the problem is specious; you really shouldn't have to have training to read documentation.

----------

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