Why Open Source Documentation is of Low Quality

By Xah Lee. Date:

Previously i've made criticisms on Python's documentations problems. [see How to Improve Python Doc; Notes on Rewriting Python Regex Doc]

I have indicated that a exemplary documentation is Wolfram Research's Mathematica language. (available online at http://reference.wolfram.com/mathematica/guide/Mathematica.html [https://reference.wolfram.com/language/] )

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 (JScript). See http://msdn.microsoft.com/en-us/library/hbxc2t98

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.

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 http://java.sun.com/j2se/1.4.2/docs/api/index.html) 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.

In general the fundamental reason that Perl, Python, Unix, Apache etc documentations are extremely bad in multiple aspects is because of Open Source fanaticism. The fanaticism has made it that Open Source people simply became UNABLE to discern quality. This situation can be seen in the responses of criticisms of Open Source docs. What made the situation worse is the Open Source's mantra of “contribution” — holding hostility any negative criticism unless the critic “contributed” without charge.

Another important point is that the Open Sourcers 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 Open Source doc criminally incompetent. Open Source has created tools that take far more energy and time than writing manuals. Lack of resource of course CAN be a contributing reason, along with Open Source coder's general lack of ability to write well, among other reasons, but the main cause as i have stated above, is Open Source fanaticism. It is that which have made them blind.

PS just to note, that my use of Open Source here does not include Free Software Foundation's Gnu's Not Unix project. GNU project in general has 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 Open Source ones mentioned above.