OpenSource documentation problems

[Xah Lee]

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
 xah at xahlee.org
∑ http://xahlee.org/