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.
-- 
https://mail.python.org/mailman/listinfo/python-list

Reply via email to