-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 [EMAIL PROTECTED] wrote: > 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).
<snip> >>> 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. Joe -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFF2hkciXBCVWpc5J4RApdbAKCkLylJoCfXFG5t/znBDYz+1NB1zwCgtkgD K+Quc4Ijlo6kZtoHvO2CVHg= =pUjl -----END PGP SIGNATURE----- -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
