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 Arthur-Milchior, docs@python, rhettinger
Date 2021-12-26.21:51:54
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1640555514.27.0.245230799483.issue46182@roundup.psfhosted.org>
In-reply-to
Content
I'm reluctant to give any more space to the least important case, one that rarely arises in practice.  The text in the PR is wordy and IMO creates more confusion that it solves.

Per the dev-guide, we mostly avoid "preachy" text.  No, "it is recommended to avoid the single argument form".  In the unlikely event that a person needs this, we are not recommending against it.  It is in fact supported, tested, and mentioned in the documentation.  And to the extend we care to nudge users in one direction or another, the traditional way to deemphasize a feature is spend less time and space talking about it :-) 

At this point, I recommend just letting it be.  It feels like we're going down a rabbit hole here rather than solving problems that users actually have.  These features are almost two decades old and the docs have been stable for a long time.  If there were a significant communication issue here, we would have known long ago.

To gain an appreciation for the challenges we face in documentation, take a look at the discussion in https://bugs.python.org/issue46173 .  

In the case of super(), more words don't make the docs better; it just adds more text that a user has to fight through to get the gestalt of what is going on.  When I talk to advanced users of the language, they almost never think of super() in more detail than is covered in the docs; instead, they've grokked the central concept of next-in-mro and that it is commonly used in two ways either to call parent class or to implement cooperative multiple inheritance.  Ideally, we want to lead readers to that same understanding.  IMO, detailing the mechnanics of uncommon cases takes us in the opposite direction.
History
Date User Action Args
2021-12-26 21:51:55rhettingersetrecipients: + rhettinger, docs@python, Arthur-Milchior
2021-12-26 21:51:54rhettingersetmessageid: <1640555514.27.0.245230799483.issue46182@roundup.psfhosted.org>
2021-12-26 21:51:54rhettingerlinkissue46182 messages
2021-12-26 21:51:54rhettingercreate