[EMAIL PROTECTED] wrote: >Greetings all, > >My recent difficulties with printer and mail setup have led to to the point >where I simply must express my thoughts on "RTFM". > >1. I'm beginning that this should be the credo to linux use. Which >would be >fine if reading the "fine" manual didn't imply previous >knowledge of the OS >or app that one is reading on
Depends on the mentality of the user. There are users who are willing to help other users, while there are others who'd only help if the clueless user has exhausted all means aside from reading the manual, some simply help people who are encumbered by problems that aren't stated in the manual (there are problems and techniques that can't be learned via the manual alone), while others simply would give RTFM (the elitists).Maybe we should re- assess ourselves as users - we are all newbies (we can't know everything). The oldies are actually newbies with experience, and have been there (they were once newbies too) where the complete newbies are now. I think that experience would be the best teacher, and that a HOWTO is more appropriate than a man page for the newbies. The man page does help, but most of time presents the arcane intricacies together with the basics. >2. Here's an appropriate analogy: > >I've decided to learn .... Hebrew, after some research, I find an >instructor (eg a mailing list) and am given directions to download a >complete list of standard vocabulary, syntax, sentence structure, >and other tools necessary to learn this new language. I begin to >read these documents, only to discover within the first page, that >it has been written from the point of someone ~raised~ with Hebrew. >Their are shortcuts, strange citations, symbols and references to >structures that only make sense once Hebrew has ~been learned~. It >becomes an excercise in circular reasoning. In order to learn A, one >must read B, which extensively references C, which directs one >to re-read A. If in doubt return to C ... or was that B. Sometimes it becomes even worse - a recursive reasoning that would require one to have an intimate knowledge of OS theory, design, and experience just to overcome such situations. Admittedly, efforts must be exerted to provide more friendly documentation for software. There are even times that hitting the books or the man pages won't help at all - rather, it is experience by other people that is needed to overcome the kinds of problems that the books and man pages won't give a hint on. >Do you see. No-one can possible be expected to ~read for >comprehension~ a manual that has ~not~ been written with a >~complete~ newbie in mind. In a previous response to email regarding >my ongoing email problems, I made reference to the Mutt manual. >Section 6.3 Configuration Variable is chock full of all kinds of >variable that can be invoked through command line or >the config file. The author(s) forgot to include any ~in context~ >examples or to identify which of these variables requires the #$% >~set~ prefix. Ah well ... I guess I have the time to configure, >test, oops ... remove the "set", re-save, test again .... until I >have it running as I wish. If you're a newbie and you'll be presented with this kind of manual, more likely than not you'll be expected to do such. Unless someone or a better HOWTO exists, it's just so sad:( >Yep ... allowing the user to have complete and total control over >the way >their system runs is a grand idea. I actually fully support >it (hence my refusal to cave-in and use M-crap). But somewhere along >the line, bells and whistles should have gone off that all the >configuring in the world WILL NOT HAPPEN without clear, concise, and >comprehensible instructions/directions. This is actually a problem since the beginning of UNIX history - the persistence of arcane literature known as the man pages. Over the years, there has been a general effort to produce more human- comprehensible (as well as newbie friendly) literature such as more detailed HOWTO's (Linux documentation is a very good example). UNIX was initially designed as a programmer's OS (we can't deny that) thus the quality of some arcane literature - it wasn't meant for the uninitiated. >I vow that once I've overcome the current mail hurdle ~I~ will >document my trials and errors and post them to the web in a format >that a complete and utter newbie will be able to understand. I've >got to assume that no one is getting rich off the constant mistakes >and misconfigurations that many people suffer from. Nah .... that >would be too much like BG. I'd wait for that time :) Sure would help lots of people. But please do check the net for any duplicate literature. Or if you are part of a LUG, you can suggest that your project would be part of a local effort to provide easy-to-comprehend linux documentation. Who knows, yours might be the best of its kind out there. >Last words (for now) ... in order for Open Source to have continued >and >increasing validity, it ~has~ to mean more than just "change at >will". It must include "if I've written the application, I will >include ~clear~ instructions". The Free Software Foundation is very adamant in the production of free and good documentation for free software. I believe others are also into this, as this is a movement in progress. Paolo Falcone __________________________________ www.edsamail.com
