discuss: Thread: netslaves article

I'm going to `waste' bandwidth by quoting an article that ran on
netslaves, at http://www.netslaves.com/comments/983976069.shtml

The state of documentation is far better than she indicates, but
there is *some* truth in what she says. Even though she is very wrong
on some points, she correctly outlines our challenge - making our
HOWTOs more accessible and readable for non geeks.

So, without further ado...


Linux Must Have Documentation Human Beings Can Consume

The HOW-TOs and FAQs are funny. They're written in some strange moon
language. Other moon language speakers can read these things with
ease. They meet in dark rooms and exchange plans for the domination of
their world in their strange moon language script. Unfortunately, for
the rest of us, moon language was only offered as a graduate option
and we were too busy jerking off in classes studying caching schema in
NUMA machines to get around to taking it.

Who wrote these things?

The thing about Linux documentation is that it backs the oft-blabbered
fallacy that engineers, as a whole, cannot communicate with the
outside universe and those that can have some sort of strange gift
from the Heavens. These bits and pieces of documentation are so
difficult to read that one would think they were summonings for Dread
Cthulhu. "Install a video card, summon an Elder God! The joke is on
you! Ha ha ha!"

Worse, when faced with a problem, where does one have to go? That's
right. The HOW-TO files.

There is a standard engineering paradigm where all systems must be
fully specified and documented. Linux is not fully specified and
documented. It is fragmented, with bits and pieces of information
available, written by those who were disciplined enough, crazy enough,
or plain bored enough to write up documentation. Sure, one can go out
and drop a bunch of cash on O'Reilly books or one of the many "Linux
in a minute" books, but those books don't help when a piece of
hardware goes kaput, or a new application has gone ahead and wiped out
the system partition. Again.

Without some comprehensive, available documentation, Linux will
/always/ be simply a hobby operating system and never taken seriously.
Polish, professionalism, and clear documentation counts for more than
any geek will give it credit. Certainly, the whole "cathedral and
bazaar" model makes everyone warm and fuzzy, but it doesn't lead to
comprehensive documents on how to use and abuse the system targeted to
be read and used by consumers. Strong documentation is worth a million
dollars, but, right now, looking over most of the HOWT-TOs, these
documents and five bucks can get you a tripple latte mocha at
Starbucks.


-- 
Dr. David C. Merrill                     http://www.lupercalia.net
Linux Documentation Project                   ####@####.####
Collection Editor & Coordinator            http://www.linuxdoc.org
                                       Finger me for my public key

Hell is empty and all the devils are here.
		-- Wm. Shakespeare, "The Tempest"