Path: csiph.com!usenet.pasdenom.info!news.albasani.net!newsfeed.freenet.ag!news2.euro.net!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail Return-Path: X-Original-To: python-list@python.org Delivered-To: python-list@mail.python.org X-Spam-Status: OK 0.024 X-Spam-Evidence: '*H*': 0.95; '*S*': 0.00; 'subject:Python': 0.05; 'python': 0.09; 'incorrect': 0.09; 'none.': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'worse': 0.09; 'htmlparser': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'wider': 0.16; 'wrote:': 0.17; 'examples': 0.18; 'feb': 0.19; 'followed': 0.20; 'mostly': 0.20; 'written': 0.20; 'either.': 0.22; 'programming': 0.23; "i've": 0.23; 'header:User-Agent:1': 0.26; 'wrote': 0.26; 'plain': 0.27; 'correct': 0.28; 'header:X-Complaints-To:1': 0.28; 'post': 0.28; '(maybe': 0.29; 'bad.': 0.29; "d'aprano": 0.29; 'steven': 0.29; '"the': 0.29; "i'm": 0.29; 'maybe': 0.29; 'stuff': 0.30; 'getting': 0.33; 'docs': 0.33; 'to:addr:python-list': 0.33; 'languages': 0.33; 'community': 0.35; 'sometimes': 0.35; 'subject:?': 0.35; 'received:org': 0.36; 'programmers': 0.36; 'should': 0.36; 'charset:us-ascii': 0.36; 'moment': 0.37; 'subject:: ': 0.38; 'mean': 0.38; 'some': 0.38; 'to:addr:python.org': 0.39; 'header:Received:5': 0.40; 'think': 0.40; 'days': 0.60; 'easy': 0.60; 'most': 0.61; 'first': 0.61; 'back': 0.62; 'worth': 0.63; 'more': 0.63; 'moments': 0.65; 'audience': 0.71; 'groups.': 0.78; '2013': 0.84; 'audience,': 0.84; 'find.': 0.84; 'newcomer': 0.84; 'received:sd.cox.net': 0.84; 'titled:': 0.84; 'subject:you': 0.88 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: python-list@python.org To: python-list@python.org From: rh Subject: Re: Do you feel bad because of the Python docs? Date: Tue, 26 Feb 2013 12:18:01 -0800 References: <512cb0a0$0$30001$c3e8da3$5496439d@news.astraweb.com> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Gmane-NNTP-Posting-Host: ip68-227-87-145.sb.sd.cox.net User-Agent: dsodnetnin X-Mailer: EZnn0.37p X-Newsreader: EZnn0.37p X-Gmane-NNTP-Posting-Host: EZnn0.37p Original-Received: from slem by 1.1 with local X-No-Archive: yes Archive: no X-Archive: expiry=11 X-Archive: encrypt X-Operating-System: Barebones_6.1 X-Gmane-NNTP-Posting-Host: 192.168.1.1 X-NNTP-Posting-Host: 192.168.1.1 Mail-Copies-To: never X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: General discussion list for the Python programming language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 34 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1361909862 news.xs4all.nl 6875 [2001:888:2000:d::a6]:35278 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:40002 On 26 Feb 2013 12:54:56 GMT Steven D'Aprano wrote: > One week ago, "JoePie91" wrote a blog post challenging the Python > community and the state of Python documentation, titled: > > "The Python documentation is bad, and you should feel bad". No I do not feel bad. I did not read the post either. As a newcomer to python I found the docs to be difficult. I'm getting used to reading them after a few months. Any document is written for some audience, maybe python needs to target wider audience groups. One for programmers from other languages (maybe one for each major language?). One for those new to programming and python at the same time. One for python programmers (have mostly that now, I think) Etc. If I harken back to those days when I first used man pages it was a moment of "Wow! This is great!" followed by many moments of "Hmmmm, do they mean this...?". Incorrect docs are worse than none. I think most of the python docs I've read have been correct although sometimes stuff is just missing. Like threading.local was not easy to find. HTMLParser is avoided by lots of people because it requires lots of prior knowledge. Examples are worth more then plain old doc.