Perl's documentation has come of age: http://perldoc.perl.org/
Python morons really need to learn: • ample example codes. • example codes are linked to the appropriate doc location for each code word in the example. • written in a task-oriented style, or manifest-functionality style. That is, it does not have fucking pretensions of a computer science mode or fucking clean aloofness. It either is oriented towards tasks programers need to do, as in module documentations, or document the language as it manifestly functions. (e.g. input, output, side effects; concrete description of object's methods and variables.) The Python docs (docs.python.org), is organized in some incomprehensible computer sciency structure that is impossible to find anything. And the entire doc go to the extra mile to avoid any task-oriented writing or examples as if those are pests that can lower their fucking status. And when the Python docs tries to document its functions, it doesn't talk straight but instead throwing fucking bunch of abstract objects and models jargons. -------------- The Perl documentations, at least in its presentation (organization, focus) and technology (DHTML...) aspects, has come of age. However, the Perl doc's content and writing per se, remains the worst garbage possible. (and Python's is in the same ball park) The negative aspects people want to avoid are: • do not tech geek. Both perlers and pythoners do tech geeking. That is, mentioning of extraneous jargons, warnings, implementation details, little style guide here and there, unconscious opportunistic OpenSource propaganda pitch-ins, historic information provisions, insider jokes, author masturbation on language design and comparisons... etc. (with Perl, this may be understandable or irrelevant because it is their nature and design to be juvenile. They revel in it. But with Python, of its people's computer sciency aloofness and cleanness pretensions meanwhile don't really exhibit any ability to think and write better, are one fucking assholes.) • Do think clearly before writing. Both Perl and Python docs's writing quality are extremely bad. What they primarily lack is the ability to think clearly before writing. Perl docs write in the fashion of happy-go-lucky juvenile ramble, and Pythoner's in the fashion of computer sciency confoundedness. Both are incomprehensible. One easy way to test this, is for Pythoners to read Perl docs and vice versa. Pythoners will find that, you really don't know what the fuck the Perlers are talking about. Same with Perler with Python docs. However, you will not get the same feeling on well written docs, such as Java or Mathematica. (assume that the people here have been in the programing industry for several years, and are not familiar with the other languages in question.) What the Perlers & Pythoners need to do, is to horn their skills outside of coding. Study philosophy, study economics, history, social sciences, and mathematics. Also, study functional programing or hang out in functional programing communities or hardcore GNU community many also improve vastly your critical thinking and doc writing abilities. ------------ More about documentation can be found here: http://www.xahlee.org/UnixResource_dir/writ/gubni_papri.html Xah [EMAIL PROTECTED] ∑ http://xahlee.org/ -- http://mail.python.org/mailman/listinfo/python-list