Learn Technical Writing from Unix Man in 10 Days

[Jason Earl]

On Sat, Apr 28 2012, Steven D'Aprano wrote:

> On Sat, 28 Apr 2012 14:55:42 -0700, Xah Lee wrote:
>
>> Learn Technical Writing from Unix Man in 10 Days
>> 
>> Quote from man apt-get:
>> 
>>     remove
>>         remove is identical to install except that packages are
>> removed
>>         instead of installed.
>
>
> Do you also expect the documentation to define "except", "instead", "is", 
> "to" and "the"?
>
> If you don't know what "install" and "remove" means, then you need an 
> English dictionary, not a technical manual.

It is considerably worse than that.  If you look at what the
documentation for apt-get actually says, instead of just the badly
mangled version that Xah shares you would realize that the post was
basically a bald-face troll.

The rest of Xah's links in this particular article was even worse.  For
the most part he was criticizing documentation flaws that have
disappeared years ago.

Heck, his criticism of Emacs' missing documentation has been fixed since
Emacs 21 (the Emacs developers are currently getting ready to release
Emacs 24).  His criticism of git's documentation is also grossly
misleading.  kernel.org still has the empty directories, but git-scm.org
has been the official home for git's documentation for years.

I am sure that the rest of the examples are just as ridiculous.  I tend
to like Xah's writing.  Heck, I even sent a few bucks his way as thanks
for his Emacs Lisp tutorials.  However, that particular post was simply
ridiculous.

Jason