classification
Title: Expand the style guide
Type: Stage:
Components: Documentation Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2011-05-10 06:51 by rhettinger, last changed 2011-05-10 07:39 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
style.diff rhettinger, 2011-05-10 06:51 Draft of additions to the style guide review
Messages (5)
msg135681 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-05-10 06:58
Sounds very good to me.

One small thing: in the first para of "Audience", there's a "talk down them" which looks funny to me in this word order.

One question: I could imagine wording like "this is rarely needed" instead of "this is experts only" -- would you say it will be effective in making people think if they really want to do that?
msg135683 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-05-10 07:10
> there's a "talk down them" which looks funny to me in this word order.

It was missing a word.  Should be "talk down to them".  Thanks for spotting this -- I fix it in the commit.

> One question: I could imagine wording like 
> "this is rarely needed" instead of "this is experts only" 
> -- would you say it will be effective in making people
> think if they really want to do that?

Something along these lines would be a step in the right direction (though "rarely needed" is problematic if happens to match the readers need at the moment).  At this point, I would be happy just to get rid of the danger-experts-only remarks.  Just about any substitute would be better.
msg135684 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-05-10 07:11
And I sincerely hope we don't have any docs that say "if you don't know what this is, you don't need it" instead of an explanation :)
msg135685 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-05-10 07:36
New changeset d5d91b14b238 by Raymond Hettinger in branch '3.2':
Issue 12047: Expand the style guide.
http://hg.python.org/cpython/rev/d5d91b14b238
msg135686 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-05-10 07:39
New changeset 50a5e271edf9 by Raymond Hettinger in branch '2.7':
Issue 12047: Expand the style guide.
http://hg.python.org/cpython/rev/50a5e271edf9
History
Date User Action Args
2011-05-10 07:39:40rhettingersetstatus: open -> closed
resolution: fixed
2011-05-10 07:39:11python-devsetmessages: + msg135686
2011-05-10 07:36:44python-devsetnosy: + python-dev
messages: + msg135685
2011-05-10 07:11:50georg.brandlsetmessages: + msg135684
2011-05-10 07:10:08rhettingersetmessages: + msg135683
2011-05-10 06:58:59georg.brandlsetmessages: + msg135681
2011-05-10 06:51:17rhettingercreate