previously i've made serious criticisms on Python's documentations problems. (see http://xahlee.org/perl-python/re-write_notes.html )
I have indicated that a exemplary documentation is Wolfram Research Incorporated's Mathematica language. (available online at http://documents.wolfram.com/mathematica/ ) Since Mathematica is a proprietary language costing over a thousand dollars and most people in the IT industry are not familiar with it, i like to announce a new discovery: this week i happened to read the documentation of Microsoft's JavaScript. See http://msdn.microsoft.com/library/en-us/script56/html/js56jsconjscriptfundamentals.asp This entire documentary is a paragon of technical writing. It has clarity, conciseness, and precision. It does not abuse jargons, it doesn't ramble, it doesn't exhibit author masturbation, and it covers its area extremely well and complete. The documentation set are very well organized into 3 sections: Fundamentals, Advanced, Reference. The tutorial section “fundamentals” is extremely simple and to the point. The “advanced” section gives a very concise yet easy to read on some fine details of the language. And its language reference section is complete and exact. I would like the IT industry programers and the OpenSource fuckheads to take note of this documentation so that you can learn. Also, this is not the only good documentation in the industry. As i have indicated, Mathematica documentation is equally excellent. In fact, the official Java documentation (so-called Java API by Sun Microsystems) is also extremely well-written, even though that Java the language is unnecessarily very complex and involves far more technical concepts that necessitate use of proper jargons as can be seen in their doc. A additional note i like to tell the OpenSource coding morons in the industry, is that in general the fundamental reason that Perl, Python, Unix, Apache etc documentations are extremely bad in multiple aspects is because of OpenSource fanaticism. The fanaticism has made it that OpenSource people simply became UNABLE to discern quality. This situation can be seen in the responses of criticisms of OpenSource docs. What made the situation worse is the OpenSource's mantra of “contribution” — holding hostile any negative criticism unless the critic “contributed” without charge. Another important point i should point out is that the OpenSource morons tend to attribute “lack of resources” as a excuse for their lack of quality. (when they are kicked hard to finally admit that they do lack quality in the first place) No, it is not lack of resources that made the OpenSource doc criminally incompetent. OpenSource has created tools that take far more energy and time than writing manuals. Lack of resource of course CAN be a contribution reason, along with OpenSource coder's general lack of ability to write well, among other reasons, but the main cause as i have stated above, is OpenSource fanaticism. It is that which have made them blind. PS just to note, that my use of OpenSource here do not include Free Software Foundation's Gnu's Not Unix project. GNU project in general has very excellent documentation. GNU docs are geeky in comparison to the commercial entity's docs, but do not exhibit jargon abuse, rambling, author masturbation, or hodgepodge as do the OpenSource ones mentioned above. Xah [EMAIL PROTECTED] ∑ http://xahlee.org/ -- http://mail.python.org/mailman/listinfo/python-list
