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


--
To UNSUBSCRIBE, email to debian-user-REQUEST@xxxxxxxxxxxxxxxx
with a subject of "unsubscribe". Trouble? Contact listmaster@xxxxxxxxxxxxxxxx

Relevant Pages

  • Re: Programming PowerPC on Mac
    ... The documentation about how to program Windows with assembly language was, ... Linux and X and such with LuxAsm...because, over on Linux, it's the same ... There's nothing "official" only what ordinary developers (like ...
    (alt.lang.asm)
  • Linux Frequently Asked Questions with Answers (Part 6 of 6)
    ... stable kernel) you have discovered a bug in GCC. ... Refer to: ("The Machine Runs ... Linux is a very good memory tester--much better than MS-DOS based ... documentation that comes with util-linux to find out how to do this. ...
    (comp.os.linux.misc)
  • Linux Frequently Asked Questions with Answers (Part 6 of 6)
    ... stable kernel) you have discovered a bug in GCC. ... Refer to: ("The Machine Runs ... Linux is a very good memory tester--much better than MS-DOS based ... documentation that comes with util-linux to find out how to do this. ...
    (comp.os.linux.misc)
  • Linux Frequently Asked Questions with Answers (Part 6 of 6)
    ... stable kernel) you have discovered a bug in GCC. ... Refer to: ("The Machine Runs ... Linux is a very good memory tester--much better than MS-DOS based ... documentation that comes with util-linux to find out how to do this. ...
    (comp.os.linux.misc)
  • Linux Frequently Asked Questions with Answers (Part 6 of 6)
    ... stable kernel) you have discovered a bug in GCC. ... Refer to: ("The Machine Runs ... Linux is a very good memory tester--much better than MS-DOS based ... documentation that comes with util-linux to find out how to do this. ...
    (comp.os.linux.misc)