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.014 X-Spam-Evidence: '*H*': 0.97; '*S*': 0.00; 'subject:Python': 0.05; 'suppose': 0.07; 'python': 0.09; 'answering': 0.09; 'beginners': 0.09; 'considered.': 0.09; 'integral': 0.09; 'url:faqs': 0.09; 'ignore': 0.13; 'paragraphs,': 0.16; 'url:catb': 0.16; 'usability': 0.17; 'module': 0.19; 'doc': 0.22; 'example': 0.23; 'header:In-Reply-To:1': 0.25; 'set.': 0.27; 'message- id:@mail.gmail.com': 0.27; 'chris': 0.28; '(and': 0.32; 'could': 0.32; 'says': 0.33; 'docs': 0.33; 'to:addr:python-list': 0.33; 'languages': 0.33; 'tutorial': 0.33; 'received:google.com': 0.34; 'list': 0.35; 'subject:?': 0.35; 'but': 0.36; 'url:org': 0.36; 'should': 0.36; 'problems': 0.36; 'level': 0.37; 'subject:: ': 0.38; 'some': 0.38; 'to:addr:python.org': 0.39; 'list,': 0.39; 'stand': 0.61; 'more': 0.63; 'reached': 0.65; 'improvements': 0.65; 'quality': 0.69; 'language!': 0.84; 'subject:you': 0.88; 'browsing': 0.93 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:x-received:in-reply-to:references:date:message-id :subject:from:to:content-type:content-transfer-encoding; bh=2mh6qvsFefwUz14t1cTv82blMGNx03vUibu2r8BKvPE=; b=IPZDAa7PDSjPvQYuz7mtFQQLmzDFyem4ohErQ6YrMv74hxHz7JoB0Wsatm1jSt7pMt Bb1hzxEdb9nEht3HjChHEfEV7TlEBrRjYYWiQk4qvXSvCtulCIs9ziFkOx2An8tFhUzA Vv/a7IKgJyp/fID04fOvrfQsrC0PCIBoeZHtOjULhXkIJvMi9QI/QNwQCYIMmMHhz+Dh VSdlR83ef9cft827WPSRcNlKQ9qPBUKpadZs6wLGCa33wMJv0rIbWtAURJAdGwvBy1N6 Oz5MYtqKW8CQ3TJuk4Cj2p/NS8aVV3WgSBeEwgfGI0tlNWcEJz5SYg8Ta+HQ0vaP126p XRyg== MIME-Version: 1.0 X-Received: by 10.50.195.134 with SMTP id ie6mr8901566igc.6.1362027598698; Wed, 27 Feb 2013 20:59:58 -0800 (PST) In-Reply-To: References: <512cb0a0$0$30001$c3e8da3$5496439d@news.astraweb.com> Date: Wed, 27 Feb 2013 21:59:58 -0700 Subject: Re: Do you feel bad because of the Python docs? From: Jason Friedman To: python-list@python.org Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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: 24 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1362028012 news.xs4all.nl 6942 [2001:888:2000:d::a6]:53247 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:40107 > Python has a nice Tutorial for beginners. It is an integral part of the d= oc > set. To ignore that (and the indexes) in discussing the usability of Pyth= on > docs by beginners is to lie. (If beginners who actually read the tutorial > have problems with particular paragraphs, improvements can be and have be= en > made.) I never thought about the quality of the Python docs until reading these posts. I started with Python by reading the tutorial and browsing the module pages and have reached some level of competency. I suppose the module pages could stand to have more examples, but as Chris Angelico says this list should be considered part of the documentation, in which case the documents plus this list effectively give me any example I am wanting. I am very grateful to those who have given their time writing the existing documentation, answering questions on this list, and of course writing the language! Python has allowed me to be more successful at my job than the other languages I considered. The lazy and workable approach is to read the module documentation, make a reasonable effort, follow http://www.catb.org/esr/faqs/smart-questions.html, and voil=C3=A0.