classification
Title: "Economy of Expression" section outdated
Type: Stage:
Components: Devguide, Documentation Versions: Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, pitrou, python-dev, rhettinger, tshepang
Priority: low Keywords: easy

Created on 2012-07-07 06:03 by chris.jerdonek, last changed 2012-09-23 16:39 by rhettinger. This issue is now closed.

Messages (6)
msg164788 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-07 06:03
The "Economy of Expression" section of the Dev Guide's "Documenting Python"--

http://docs.python.org/devguide/documenting.html#economy-of-expression

says, "The documentation for super() is an example of where a good deal of information was condensed into a few short paragraphs."

However, the documentation for super() is now nine short paragraphs.  Back in Python 2.2 (when super() was introduced), the description really was only two short paragraphs (along with a brief code snippet):

http://docs.python.org/release/2.2.3/lib/built-in-funcs.html

So this might no longer be the best example.
msg164798 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2012-07-07 09:57
The super() doc is also a good example of unreadable jargon ("dynamic execution environment" ??). Nowhere is it obvious to a beginner what super() is *practically* used for.
msg164962 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-07-08 04:05
The point was that the docs shouldn't "write a book" where briefer explanations suffice.  The mention of super() may not be the best example because many "experts" still don't get what it is all about regardless of how much or how little much is written.

FWIW, the original two short paragraphs led to a good deal of confusion resulting in people declaring super() to be either inscrutable, unusable, or both.
msg171041 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-23 14:16
IMHO the paragraph about super() can be dropped altogether.
msg171057 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-23 16:38
New changeset 100909b4def0 by Raymond Hettinger in branch 'default':
Issue #15270.  Appease critics by removing a reference to the docs for super().
http://hg.python.org/devguide/rev/100909b4def0
msg171058 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-09-23 16:39
This whole discussion was inane.
History
Date User Action Args
2012-09-23 16:39:41rhettingersetstatus: open -> closed
resolution: fixed
messages: + msg171058
2012-09-23 16:38:20python-devsetnosy: + python-dev
messages: + msg171057
2012-09-23 14:16:13ezio.melottisetmessages: + msg171041
2012-07-13 19:01:43tshepangsetnosy: + tshepang
2012-07-09 05:00:48eric.araujosetnosy: + eric.araujo
2012-07-08 04:05:22rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger
messages: + msg164962
2012-07-07 09:57:05pitrousetnosy: + rhettinger, pitrou, docs@python
messages: + msg164798

assignee: docs@python
components: + Documentation
2012-07-07 06:03:48chris.jerdonekcreate