Idiocy of Computer Language Docs: Unix, Python, Perl, Haskell
Learn Technical Writing from Unix Man in 10 Minutes
Quote from man apt-get, 2011-01-03:
remove
remove is identical to install except that packages are removed instead of installed.
Translation:
kicking
kicking is identical to kissing except that receiver is kicked instead of kissed.
Superb Wolfram Documentation
2011-01-03 Worked with Mathematica for a whole day yesterday, after about 10 years hiatus. Very nice. Mathematica lang and doc, is quite unique.
Most other langs drivel with jargons, pettiness, comp-sci pretentiousness, while their content is mathematically garbage. e.g.
• Mumble jumple obscurantism (perl, unix)
• Promoting Object Oriented Programing as proper-engineering (java)
• Impractical and ivory-tower academic obsession as in Scheme and Haskell ( currying, tail recursion, closure, call-cc, lisp1 lisp2, and monad.)
(See: What are OOP's Jargons and Complexities • Language, Purity, Cult, and Deception.)
Mathematica, in its doc, is plain and simple. None of the jargon and pretention. Very easy to understand. Yet, some of its function's technical aspects are far more scholarly abstruse than any other lang (dealing with advanced math special functions that typically only a few thousand people in the world understand.).
A Gander into the Idiocies
Here is a gander into the doc drivel in common langs.
Unix Man Page
unix man page starts with this type of obscurantism:
SYNOPSIS gzip [ -acdfhlLnNrtvV19 ] [-S suffix] [ name ... ] gunzip [ -acfhlLnNrtvV ] [-S suffix] [ name ... ] zcat [ -fhLV ] [ name ... ]
Here, the mindset of unix idiots, is that somehow this “synopsis” preamble is technically precise and superior. They are thinking that it captures the full range of syntax in the most concise way.
In practice, nobody reads it. It's actually not accurate as one'd thought. It is machine unreadable and human incomprehensible. Worse of all, the semantic of unix software's options are the worst rape to any possible science in computer science.
See also:
Python
In Python, you see this kinda garbage collection:
Here, the mindset of the Python idiots is similar to the unix tech geekers. They think that using the BNF notation makes their doc more clear and precise.
This incomprehensible parser compiler oriented view is the ONLY thing you get if you want to know how to do conditional, loop, lambda, etc.
For much more, see: Python Documentation Problems .
Perl
Now, let's look at how Perl cultivates its cult:
The first paragraph tells carpenters that a hammer is made of a handle and a head, and you use it by swinging and banging.
The second paragraph waxes Python in, gently reminding you the context of pride.
The third paragraph, you are initialized to their lingo “DWIM” (stands for Dim Wit I Am).
Juvenile humor is a characteristic of Perl's docs. It's a standalone cult. They have “perl republic”, “state of the onion”, “apocalypse”, “perl monger”, “perl golf”, etc. 〔see Larry Wall and Cults〕 Another trait is irrelevant rambling. For example, in the above you see: “Perl borrows syntax and concepts from many languages: awk, sed, C, Bourne Shell, Smalltalk, Lisp and even English.”.
For a example of perl doc's maturity and knowledge of math, see:
However, overall, Perl doc is more practically usable than Python's.
Haskell
Here is a example of ivory-tower idiocy, from Haskellers:
Note the words “Hindley-Milner”, “polymorphic”, “static type semantics”, “overloaded operations”.
The reason they wrote their doc like that is because they are academicians. You might think that their writing is really scholarly, mathematically meaningful, full of rigor, and the daunting appearance must be due to the advanced math ideas by necessity. The irony is that the writing is actually most lousy tech writing. Most of their use of computer science jargons are unnecessary to the point of being irrelevant.
For some exposition of esoterism, see: World Multiconference on Systemics, Cybernetics and Informatics .