Path: csiph.com!usenet.pasdenom.info!weretis.net!feeder4.news.weretis.net!ecngs!feeder2.ecngs.de!newsfeed.freenet.ag!news2.euro.net!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path: <python-python-list@m.gmane.org>
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; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'sure,': 0.09; 'cases': 0.15; 'enough.': 0.16; 'from:addr:pitrou.net': 0.16; 'from:addr:solipsis': 0.16; 'from:name:antoine pitrou': 0.16; 'message-id:@post.gmane.org': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'succinct': 0.16; 'header:User-Agent:1': 0.26; 'instead.': 0.27; 'header:X-Complaints-To:1': 0.28; 'all.': 0.28; "d'aprano": 0.29; 'steven': 0.29; 'writes:': 0.29; 'url:python': 0.32; 'docs': 0.33; 'doubt': 0.33; 'to:addr:python-list': 0.33; 'subject:?': 0.35; 'received:org': 0.36; 'url:org': 0.36; 'compare': 0.36; 'should': 0.36; 'charset:us-ascii': 0.36; 'subject:: ': 0.38; 'url:docs': 0.38; 'url:en': 0.38; 'to:addr:python.org': 0.39; 'header:Received:5': 0.40; 'valuable': 0.60; 'url:index': 0.61; 'details': 0.63; 'biggest': 0.71; 'behavioral': 0.71; 'antoine.': 0.84; 'picture,': 0.84; 'received:88.163': 0.84; 'strengths,': 0.84; 'url:php': 0.86; 'subject:you': 0.88
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Antoine Pitrou <solipsis@pitrou.net>
Subject: Re: Do you feel bad because of the Python docs?
Date: Wed, 27 Feb 2013 13:17:13 +0000 (UTC)
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: sea.gmane.org
User-Agent: Loom/3.14 (http://gmane.org/)
X-Loom-IP: 88.163.232.20 (Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:19.0) Gecko/20100101 Firefox/19.0)
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.2615.1361971060.2939.python-list@python.org>
Lines: 21
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1361971060 news.xs4all.nl 6871 [2001:888:2000:d::a6]:39792
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:40058

Steven D'Aprano <steve+comp.lang.python <at> pearwood.info> writes:
> 
> It is valuable to contrast and compare the PHP and Python docs:
> 
> http://php.net/manual/en/index.php
> http://www.python.org/doc/

I suppose you should compare it with http://docs.python.org/3/ instead.

> There's no doubt that one of PHP's strengths, perhaps its biggest 
> strength, is the good state of documentation.

My (probably outdated) experience with the PHP docs is that they are very
succinct and don't document failure cases or behavioral details at all.
Sure, if you only care about the big picture, they are good enough.

Regards

Antoine.