Learn Technical Writing from Unix Man in 10 Days

[Alan Mackenzie]

Hello, Xah.

In comp.emacs Xah Lee <xahlee at gmail.com> 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.

> Translation:

>    kicking
>        kicking is identical to kissing except that receiver is kicked
>        instead of kissed.

Ha ha ha ha!!

You don't need to go as far as apt-get to see this.  Even worse is C-h f
car in Emacs.  Imagine it before the last paragraph got added.  This only
happened after a fairly long thread on emacs-devel.

There are far too many man pages which are suboptimal, to say the least.

> further readings:

[ .... ]

> DISAPPEARING URL IN DOC

> so, i was reading man git. Quote:

>    Formatted and hyperlinked version of the latest git documentation
> can
>    be viewed at http://www.kernel.org/pub/software/scm/git/docs/.

> but if you go to that url, it shows a list of over one hundred fourty
> empty dirs.

> I guess unix/linux idiots can't be bothered to have correct
> documentation. Inability to write is one thing, but they are unable to
> maintain a link or update doc?

Maintaining links is actually quite hard.  After the struggle to document
"remove", one typically has insufficient energy left over to check all
the links.

> does this ever happens to Apple's docs? If it did, i don't ever recall
> seeing it from 18 years of using Mac.

Have you ever tried to set up CUPS, the printing system?  At one point,
you're supposed to enter the "URI" of the printer, without any explanation
of what the URI of a local printer is.  At another point you're prompted
to enter "Name".  Name of what?  If you click on the "help", you get
taken to a search box, not proper docs.  Typing "name" into the search
box isn't useful.  And so it goes on.

CUPS is an Apple product.

> more records of careless dead link:

[ .... ]

-- 
Alan Mackenzie (Nuremberg, Germany).