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 chris.jerdonek, eric.araujo, ezio.melotti, nitika, rhettinger, terry.reedy
Date 2014-04-05.23:35:39
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1396740939.78.0.967237508518.issue16927@psf.upfronthosting.co.za>
In-reply-to
Content
Nikita, your additional dispatch table looks like a reasonable addition.  I'll wait on additional commentary before pushing it forward

>1 should be especially useful to people that are new to the language
Ezio, please take care not to conflate the role of reference material (where people lookup what a function does) and tutorials (which introduce, synthesize, and organize).  

Also take consider that the proposed groupings have some downsides as well (for example str and repr don't appear in the same grouping, likewise, int and round aren't in the same grouping).

And, I *really* don't want to separate-out types (that is what section 3.4 is for).  You're fighting a long-standing decision to use 3.2 to talk about the tools as functions and again in 3.4 as types.  For example, it is not helpful at all to classify range() as a type.   Its usage is better grouped with looping idioms like range, zip, enumerate, sorted, and reversed.

A possible solution is to list words in more than one category so that int() would be listed as a type conversion (so it wouldn't get separated from str(), and listed math related (so it won't be separated from round() which is another way to convert a float to an integer).

This documentation page has proven useful in its current form to a great many users.  We should take care not to muck-up one of the better pages in the docs.  In particular, we REALLY don't want to factor-out redundant text -- as reference material, each function's description needs to stand-alone.  This is not a page that people typically read start to finish in a book like form -- it is much closer to a dictionary or encyclopedia where topics are looked up directly.
History
Date User Action Args
2014-04-05 23:35:39rhettingersetrecipients: + rhettinger, terry.reedy, ezio.melotti, eric.araujo, chris.jerdonek, nitika
2014-04-05 23:35:39rhettingersetmessageid: <1396740939.78.0.967237508518.issue16927@psf.upfronthosting.co.za>
2014-04-05 23:35:39rhettingerlinkissue16927 messages
2014-04-05 23:35:39rhettingercreate