Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!news.mixmin.net!feeds.phibee-telecom.net!newsfeed.xs4all.nl!newsfeed4a.news.xs4all.nl!xs4all!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.002
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'from:addr:yahoo.co.uk': 0.04; 'subject:Python': 0.06; 'deny': 0.07; 'suggestions,': 0.07; 'corrections': 0.09; 'lawrence': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'bug': 0.12; 'suggest': 0.14; 'wrote': 0.14; 'language.': 0.14; '_do_': 0.16; 'docs.': 0.16; 'garbage': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'semantics': 0.16; 'stupidity': 0.16; 'syntactical': 0.16; 'targets': 0.16; 'student': 0.16; 'language': 0.16; 'wrote:': 0.18; 'bit': 0.19; 'not,': 0.20; 'header:User-Agent:1': 0.23; "aren't": 0.24; 'tracker': 0.26; 'header:X-Complaints-To:1': 0.27; 'header:In-Reply-To:1': 0.27; 'too.': 0.31; 'bad.': 0.31; 'helpful.': 0.31; "user's": 0.31; '"the': 0.34; 'sense': 0.34; 'skip:_ 10': 0.34; 'knows': 0.35; 'but': 0.35; 'programming,': 0.36; 'subject:skip:d 10': 0.36; 'question,': 0.38; 'somebody': 0.38; 'to:addr:python-list': 0.38; 'does': 0.39; 'to:addr:python.org': 0.39; 'received:org': 0.40; 'even': 0.60; 'most': 0.60; 'matter': 0.61; 'address': 0.63; 'email addr:gmail.com': 0.63; 'valuable': 0.63; 'our': 0.64; 'telling': 0.64; 'relatively': 0.65; 'charset:windows-1252': 0.65; 'capable': 0.67; 'subject': 0.69; 'user,': 0.69; 'lack': 0.78; 'pony': 0.84; 'edwards': 0.91
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Mark Lawrence <breamoreboy@yahoo.co.uk>
Subject: Re: Python docs disappointing
Date: Thu, 20 Nov 2014 23:22:08 +0000
References: <h4vj45$5hl$1@reader1.panix.com> <77d357fb-342e-4856-814d-0e0003164fb1@googlegroups.com> <m4lscv$nr7$1@reader1.panix.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 7bit
X-Gmane-NNTP-Posting-Host: host-92-18-14-177.as13285.net
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:31.0) Gecko/20100101 Thunderbird/31.2.0
In-Reply-To: <m4lscv$nr7$1@reader1.panix.com>
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: <https://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: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.16064.1416525904.18130.python-list@python.org>
Lines: 44
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1416525904 news.xs4all.nl 2861 [2001:888:2000:d::a6]:53435
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:81143

On 20/11/2014 23:10, Grant Edwards wrote:
> On 2014-11-20, jstnms123@gmail.com <jstnms123@gmail.com> wrote:
>
>> I write this to address the criticism which targets a user's lack of
>> responsibility for the real/implied/insinuated failings of the docs.
>> As a relatively inexperienced student of programming, I am not in any
>> position to contribute/edit the documents.
>
> Wrong.  As an inexperienced user, you are _exactly_ the right person
> to contribute/edit the documents.  A documents _always_ make sense to
> the author and to somebody who already knows the information.  They
> are often not capable of seeing what's wrong.
>
> It's those who are _not_ familiar with the subject matter who can
> often make the most valuable contributions.
>
>> THAT DOES NOT, however, DENY THE CATEGORICAL STUPIDITY OF THE
>> DOCUMENTATION: .  Not only are the semantics of the editors in
>> question, but so are the syntactical and grammatical conventions,
>> too.
>
> Then send in suggestions, corrections and improvements.  Or pony up
> and actually take over maintenance of one of the documents you think
> is so bad.
>
> The authors of the documentation aren't _intentionally_ writing things
> that other people don't understand.  If you don't understand the
> documentation or think it needs to be extended/expanded, then help
> _do_ it.
>
> Just telling somebody "the document you wrote SUCKS!" is not even a
> _tiny_ bit helpful.
>

Having seen some of the garbage that turns up on the bug tracker under 
the guise of "improvements" I suggest that many people who criticize the 
docs don't take up a career as a technical author.

-- 
My fellow Pythonistas, ask not what our language can do for you, ask
what you can do for our language.

Mark Lawrence