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 [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
