Python docs disappointing

Joel Goldstick joel.goldstick at
Thu Nov 20 17:51:27 CET 2014

On Thu, Nov 20, 2014 at 10:54 AM,  <jstnms123 at> 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 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.  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.  Semantics, even in the hands of the honest, is a fuzzy beast;  the elements of exposition and structure are not. Perhaps the inquisitive mind is correctly labeled stupid, or irresponsible, if it cannot decipher some fine piece of programming crypsis.  And perhaps not. It can just as perhaps be that there is an equal, even greater irresponsibility, on the part of those who 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 the educators in the techni
>  cal fields, than pretending any hermeneutic, an effective hermeneutic. Sadly, most of these creatures cannot tell a verb from a noun, and scarcely know where modifiers are best, most effectively, posted to qualify their objects, let alone use those same nouns and verbs and modifiers to explain the intricacies of a subject.  Tell one of these cognoscenti that language is about COMMUNICATION, and they begin pointing abstract fingers at their critics, 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 creatures who know much more than they comprehend, and much less than they need to?  If, I think, you cannot explain a thing to me, you do not understand it.  After all, I'm a lot smarter than you, and I have thankfully learned make out a fool however obscurely he covers himself.
> --

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.

Joel Goldstick

More information about the Python-list mailing list