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
