[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Old Computer Parts

Hash: SHA1

hendrik@topoi.pooq.com wrote:
> On Mon, Feb 19, 2007 at 11:23:17AM +0100, Joe Hart wrote:
>> 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).


>>> 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

Point taken.  I couldn't help laughing about the howto's.  You're spot
on.  One of the reasons I switched to Debian from Kubuntu was the
documentation.  I found out that if I wanted to know how the system
worked I had to read the Debian docs.  I figured, if Debian is the group
developing all the stuff, why should I run an offshoot that changes the
original design and adds 'beginner friendly' content.

The whole point for me getting away from Windows is I didn't like it
doing things behind my back that I had no idea what they were.

Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org


Reply to: