This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author rhettinger
Recipients barry, brett.cannon, docs@python, gregory.p.smith, ncoghlan, pablogsal, rhettinger, tim.peters, vstinner, willingc
Date 2019-06-04.01:52:55
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1559613176.0.0.465204820753.issue37134@roundup.psfhosted.org>
In-reply-to
Content
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.
History
Date User Action Args
2019-06-04 01:52:56rhettingersetrecipients: + rhettinger, tim.peters, barry, brett.cannon, gregory.p.smith, ncoghlan, vstinner, docs@python, willingc, pablogsal
2019-06-04 01:52:56rhettingersetmessageid: <1559613176.0.0.465204820753.issue37134@roundup.psfhosted.org>
2019-06-04 01:52:55rhettingerlinkissue37134 messages
2019-06-04 01:52:55rhettingercreate