Path: csiph.com!usenet.pasdenom.info!gegeweb.org!de-l.enfer-du-nord.net!feeder1.enfer-du-nord.net!newsfeed.eweka.nl!eweka.nl!feeder3.eweka.nl!newsfeed.xs4all.nl!newsfeed1.news.xs4all.nl!xs4all!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.017 X-Spam-Evidence: '*H*': 0.97; '*S*': 0.00; 'subject:Python': 0.05; 'class,': 0.07; 'python': 0.09; 'assumed': 0.09; 'beginners': 0.09; 'expectation': 0.09; 'yeah,': 0.09; 'cc:addr:python-list': 0.10; 'language': 0.14; 'adam': 0.16; 'authors.': 0.16; 'fine.': 0.16; 'manner,': 0.16; 'wrote:': 0.17; 'feb': 0.19; 'supposed': 0.21; 'combination': 0.22; 'cc:2**0': 0.23; 'raise': 0.24; 'cc:no real name:2**0': 0.24; 'cc:addr:python.org': 0.25; 'header:In- Reply-To:1': 0.25; 'am,': 0.27; 'message-id:@mail.gmail.com': 0.27; 'assert': 0.29; 'sensible': 0.29; 'strings,': 0.29; 'actively': 0.30; 'basic': 0.30; 'url:python': 0.32; 'recommended': 0.33; 'received:google.com': 0.34; 'along': 0.35; 'acceptable': 0.35; 'massive': 0.35; 'path': 0.35; 'subject:?': 0.35; "won't": 0.35; 'received:209.85': 0.35; 'there': 0.35; 'url:org': 0.36; 'programmers': 0.36; 'method': 0.36; 'itself': 0.37; 'does': 0.37; 'level': 0.37; 'rather': 0.37; 'received:209': 0.37; 'subject:: ': 0.38; 'url:docs': 0.38; 'think': 0.40; 'kind': 0.61; 'provide': 0.62; 'helping': 0.63; '26,': 0.65; 'burden': 0.65; 'learned': 0.65; 'special': 0.73; '2013': 0.84; 'manual,': 0.84; 'url:datamodel': 0.84; 'url:reference': 0.84; 'subject:you': 0.88 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=x-received:mime-version:in-reply-to:references:from:date:message-id :subject:to:cc:content-type; bh=u5VCX5QpyLU5t9a2C+0InfJNIM9jlRpN/Dsz+f0Li9w=; b=Ah6QmAoflIlUs7cPMsl9Gw0gHRG6RdbMUjVcGMQWNTnJUSFfgJmJtg/xnZXvTaQZfA DBqpLSn26dZ+7giecDk9hiPe9FNRYZ/FUL6rIZmPWEyIwaLEb9+mFqGHEMwXZzK7+IL9 JIxHl65BN7DZcZHNB0eXOCzwcHEMPeiGTAHZ4HVCEj+U3bgNiONv/T95j4HBM7upYuhN 35q14LYeSrW0RtkrUpPhCL34csT9+iqiBNZ/daF5oar+1P6/dNrawBcOc6Pg1qzWiPuP r0NQKuo387ZSAykIrp+0xx+LyVF7KlfQAXKJkxYWBVU+Fyn6WbBGB6+7lxqM0m9ukAyr /3bg== X-Received: by 10.59.13.197 with SMTP id fa5mr12423251ved.47.1361904817232; Tue, 26 Feb 2013 10:53:37 -0800 (PST) MIME-Version: 1.0 In-Reply-To: <57fd0b09-b30d-4e62-845a-aac198113a40@googlegroups.com> References: <512cb0a0$0$30001$c3e8da3$5496439d@news.astraweb.com> <57fd0b09-b30d-4e62-845a-aac198113a40@googlegroups.com> From: Devin Jeanpierre Date: Tue, 26 Feb 2013 13:52:57 -0500 Subject: Re: Do you feel bad because of the Python docs? To: "Adam W." Content-Type: text/plain; charset=UTF-8 Cc: python-list@python.org 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: 25 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1361904825 news.xs4all.nl 6953 [2001:888:2000:d::a6]:37081 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:39989 On Tue, Feb 26, 2013 at 11:38 AM, Adam W. wrote: > I think learning a language from the documentation is an unreasonable expectation and burden for the authors. That's how I learned it. The Python tutorial, together with the stdlib reference manual, are often recommended to beginners to Python in order to learn it. The combination of the documentation and consulting other programmers helped me learn the language just fine. > Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals. I would assert it isn't very kind to those even with basic fundamentals. For example, under precisely what circumstances does int() raise TypeError? You won't find that under either int's documentation, or TypeError's documentation, you have to look it up under __int__, which is _not_ a basic fundamental. And rather than helping you along the way, the documentation for int() actively misleads you by its implicature that the only acceptable types are strings, ints, and floats. And then even if you have the foresight to remember "oh yeah, isn't there a special method for this?", you have to find the documentation for __int__, which is itself is three quarters of the way down this massive page: http://docs.python.org/2/reference/datamodel.html . -- Devin