Re: Old Computer Parts
On Mon, Feb 19, 2007 at 11:23:17AM +0100, Joe Hart wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Mirko Scurk wrote:
> > Hans du Plooy wrote:
> >> On Sun, 2007-02-18 at 22:02 +0100, Joe Hart wrote:
> >
> >> No matter how easy or difficult the question you ask, there will always
> >> be some smartass who tell to you go RTFM (which is often a longer
> >> sentence to type than the answer to your question). Don't let it bother
> >> you. Eric S. Raymond's advice is good advice, but I know people can be
> >> intimidated and/or confused by some documentation out there. Heck,
> >> after more than 10 years of using linux some projects' documentation
> >> still overwhelm me. If you know absolutely nothing about a certain
> >> program or the technologies involved, it can be difficult to figure out
> >> where to start.
> >
> > One great thing about linux is huge amount of documentation and another is
> > that it is developing and introducing new stuff almost every day but lot
> > of that documentation is more than 2 years old and tells you little about
> > current
> > distro. Sometimes user of that old documentation could be even misled.
> >
>
> That is one of the major problems that I have found as well. Even
> Eric's homepage at http://www.catb.org/~esr/ is dated 18 Nov. 2005,
> which by Linux standards is old. The Linux Documetation Project at
> http://tldp.org/ has some very good articles, but quite a bit of their
> information is from 2002. Needless to say, it is sometimes difficult to
> determine which information applies. Trial and error are fine on a test
> machine, but not on a production machine.
Let's see. The developers develop something -- it could be a new tool,
it could be new ways of using old tools, it could be imcompatible with
what was there before. But unless it's documented, it's useless outside
of a small circle of friends.
So someone in the small circle of friends has to provide the primary
documentation. This could be as little as comments in C code. In the
70's when Unix was starting up, with full source code available, it was
said that the source code is the ultimate documentation. But I've
always found source code to be mighty obscure without some information
as to what it is *supposed* to do. Especially if there's millions of
lines of the stuff.
So come the second tier of documenters -- these are the ones who pore
over the C code and the realease notes and the comments and try things
out and generally mess about until they have the hang of it. What tye
understand they write down, post on the web somewhere and hope someone
can find it. If they're lucky they are organised in to some sort ot
Linux dicumentation project, or Debian documentation project or
something of the sort. If they are luckier they have contact with the
authors of the original code -- if they haven't found a new interest or
a new job or actually have the language skills to answer questions. If
we are *really* lucky we'll find code writers who are also decent
technical writers.
Then there's the kob of organising all this documentation (which has
holes of its own) into some structure that makes sense, into reference
manuals that actually point the way to want you need to know. This is
an intellectial activity on itself, and cannot adequately be automated.
However good the search engines are, they only provide pointers to the
raw material for this kind of reflective process.
This stage leads to documentation that can be used by technically
competent people to find information they need. except that the tortuous
passage fro the original developers pretty well ensures that some of it
has become lost along the way.
Finally, there is documentation for beginners -- the how-to's that tell
them how to do something, provided they have already figured out what it
is they need to to and where to find the how-to. Which probably means
they are no longer real beginners.
And, yes, I suppose we still need something for the *real* beginners.
Imagine if documentation could go through all these stages and still be
up-to-date! What a wonderful world that could be!
-- hendrik
Reply to: