Path: csiph.com!usenet.pasdenom.info!gegeweb.org!usenet-fr.net!nerim.net!novso.com!newsfeed.xs4all.nl!newsfeed4a.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
MIME-Version: 1.0
In-Reply-To: <77d357fb-342e-4856-814d-0e0003164fb1@googlegroups.com>
References: <h4vj45$5hl$1@reader1.panix.com> <77d357fb-342e-4856-814d-0e0003164fb1@googlegroups.com>
Date: Thu, 20 Nov 2014 11:51:27 -0500
Subject: Re: Python docs disappointing
From: Joel Goldstick <joel.goldstick@gmail.com>
To: jstnms123@gmail.com
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Cc: "python-list@python.org" <python-list@python.org>
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.16030.1416502295.18130.python-list@python.org>
Lines: 84
NNTP-Posting-Host: 2001:888:2000:d::a6
Xref: csiph.com comp.lang.python:81090

On Thu, Nov 20, 2014 at 10:54 AM,  <jstnms123@gmail.com> wrote:
> On Friday, July 31, 2009 2:10:45 PM UTC-6, kj wrote:
>> I'm pretty new to Python, and I like a lot overall, but I find the
>> documentation for Python rather poor, overall.
>>
>> I'm sure that Python experts don't have this problem: they have
>> internalized some good ways to access the documentation, are
>> productive with it, and therefore have lost the ability to see why
>> the Python documentations is deficient for beginners.  This explains
>> why a suboptimal situation can persist like this: those who are
>> most able fix it are also the least able to perceive it.
>>
>> I've heard similar complaints from other experienced programmers
>> who are trying out Python for the first time: poor documentation.
>>
>> Here is an *entirely typical* example: on some Unix, try
>>
>> % pydoc urllib
>>
>> The displayed documentation mention the optional parameter "data"
>> in practically every function listed (a few dozen of them).  This
>> parameter is not documented *anywhere* on that page.  All that we
>> are told is that its default value is always None.
>>
>> I'm sure that I can find a full description of this parameter if
>> I fire up Google, and search online.  In fact, more likely than
>> not, I'll find far more documentation than I want.  But my point
>> is that a programmer should not need to do this.  The full
>> documentation should be readily accessible directly through a few
>> keystrokes.
>>
>> I would love to know how experienced Python programmers quickly
>> zero in on the Python documentation they need.
>>
>> TIA!
>>
>> kynn
>
> I write this to address the criticism which targets a user's lack of resp=
onsibility for the real/implied/insinuated failings of the docs.  As a rela=
tively inexperienced student of programming, I am not in any position to co=
ntribute/edit the documents.  THAT DOES NOT, however, DENY THE CATEGORICAL =
STUPIDITY OF THE DOCUMENTATION: .  Not only are the semantics of the editor=
s in question, but so are the syntactical and grammatical conventions, too.=
  Semantics, even in the hands of the honest, is a fuzzy beast;  the elemen=
ts of exposition and structure are not. Perhaps the inquisitive mind is cor=
rectly labeled stupid, or irresponsible, if it cannot decipher some fine pi=
ece of programming crypsis.  And perhaps not. It can just as perhaps be tha=
t there is an equal, even greater irresponsibility, on the part of those wh=
o have taken up the task of clarifying the obscure to the confused.  There =
is no greater arrogance, and it seems to me particularly prevalent among th=
e educators in the techni
>  cal fields, than pretending any hermeneutic, an effective hermeneutic. S=
adly, most of these creatures cannot tell a verb from a noun, and scarcely =
know where modifiers are best, most effectively, posted to qualify their ob=
jects, let alone use those same nouns and verbs and modifiers to explain th=
e intricacies of a subject.  Tell one of these cognoscenti that language is=
 about COMMUNICATION, and they begin pointing abstract fingers at their cri=
tics, and labeling.
>
> Perhaps the reason programs are so inelegant, and so user-UNfriendly, and=
 so bug-infested, is a natural consequence, when a field is dominated by cr=
eatures who know much more than they comprehend, and much less than they ne=
ed to?  If, I think, you cannot explain a thing to me, you do not understan=
d it.  After all, I'm a lot smarter than you, and I have thankfully learned=
 make out a fool however obscurely he covers himself.
> --
> https://mail.python.org/mailman/listinfo/python-list

I learned a new word: hermeneutic

Or just WOW!.  Programming is hard, and people have just started to do
it.  Fifty years isn't that long.  It has only been 20 years or so
that the web has been around.  That makes it easier to find
information from a variety or sources -- the official docs, tutorials,
articles.  If you feel the docs are awful, write a tutorial based on
your knowledge level and experience.  Improve the situation.

I'm trying to wrap my mind around DOCUMENTION being STUPID.


--=20
Joel Goldstick
http://joelgoldstick.com