TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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 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"
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.
