[Fwd: netslaves article]

Subject: [Fwd: netslaves article]
From: Sandy Harris <sandy -at- storm -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 08 Mar 2001 23:14:49 -0500

This turned up on one of the Linux Documentation Project (www.linuxdoc.org)
mailing lists. It seemed to me it might provoke some discussion here.

-------- Original Message --------
Subject: netslaves article
Date: Thu, 8 Mar 2001 10:03:25 -0500
From: David Merrill <david -at- lupercalia -dot- net>
To: ldp-discuss <discuss -at- linuxdoc -dot- org>, ldp-review <ldp-review -at- lupercalia -dot- net>

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

Dr. David C. Merrill http://www.lupercalia.net
Linux Documentation Project david -at- lupercalia -dot- net
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"



Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**New Dates!!** San Francisco (Apr 16-17), San Jose (Mar 29-30)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15. http://ieeepcs.org/2001/

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.

Previous by Author: Re: Antwort: RE: Title for a Document about bugs
Next by Author: Re: How formal or informal?
Previous by Thread: Re: How formal or informal
Next by Thread: Re: [Fwd: netslaves article]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads