Re: Thoughts on RTFM
cmasters@nbnet.nb.ca 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
Reply to: