Re: Python docs disappointing

Path	csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!nntp.club.cc.cmu.edu!ra.nrl.navy.mil!bloom-beacon.mit.edu!bloom-beacon.mit.edu!panix!not-for-mail
From	Grant Edwards <invalid@invalid.invalid>
Newsgroups	comp.lang.python
Subject	Re: Python docs disappointing
Date	Thu, 20 Nov 2014 23:10:23 +0000 (UTC)
Organization	PANIX Public Access Internet and UNIX, NYC
Lines	36
Message-ID	<m4lscv$nr7$1@reader1.panix.com> (permalink)
References	<h4vj45$5hl$1@reader1.panix.com> <77d357fb-342e-4856-814d-0e0003164fb1@googlegroups.com>
NNTP-Posting-Host	67-130-15-94.dia.static.qwest.net
X-Trace	reader1.panix.com 1416525023 24423 67.130.15.94 (20 Nov 2014 23:10:23 GMT)
X-Complaints-To	abuse@panix.com
NNTP-Posting-Date	Thu, 20 Nov 2014 23:10:23 +0000 (UTC)
User-Agent	slrn/1.0.1 (Linux)
Xref	csiph.com comp.lang.python:81138

Show key headers only | View raw

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.

-- 
Grant Edwards               grant.b.edwards        Yow! Everybody gets free
                                  at               BORSCHT!
                              gmail.com

Thread

Re: Python docs disappointing jstnms123@gmail.com - 2014-11-20 07:54 -0800
  Re: Python docs disappointing Joel Goldstick <joel.goldstick@gmail.com> - 2014-11-20 11:51 -0500
    Re: Python docs disappointing albert@spenarnc.xs4all.nl (Albert van der Horst) - 2014-12-04 10:27 +0000
      Re: Python docs disappointing Chris Angelico <rosuav@gmail.com> - 2014-12-04 21:37 +1100
      Re: Python docs disappointing Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-12-04 22:46 +1100
      Re: Python docs disappointing jtan <admin@grails.asia> - 2014-12-05 07:33 +0800
      Re: Python docs disappointing Michael Torrie <torriem@gmail.com> - 2014-12-04 16:57 -0700
  Re: Python docs disappointing Michael Torrie <torriem@gmail.com> - 2014-11-20 09:51 -0700
  Re: Python docs disappointing Skip Montanaro <skip.montanaro@gmail.com> - 2014-11-20 11:18 -0600
  Re: Python docs disappointing Grant Edwards <invalid@invalid.invalid> - 2014-11-20 23:10 +0000
    Re: Python docs disappointing Mark Lawrence <breamoreboy@yahoo.co.uk> - 2014-11-20 23:22 +0000
  Re: Python docs disappointing Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-11-21 10:29 +1100
    Re: Python docs disappointing Grant Edwards <invalid@invalid.invalid> - 2014-11-21 16:35 +0000

csiph-web