RE: Thoughts on RTFM

2001-12-04 Thread Paul 'Baloo' Johnson
On Mon, 3 Dec 2001 [EMAIL PROTECTED] wrote:

> Some of you obviously "get it." My hats off to you!

I've done tech support for a few years for various organisations.
During my time there, I learned that Mr Maziuk has more than the right
idea.  We don't tolerate people who don't understand the simple concept
of public transportation on the lines here, I don't understand why the
tech industry has this weird notion of tollerating people who don't
understand a glorified television.

-- 
Baloo




RE: Thoughts on RTFM

2001-12-03 Thread Jeff . Chimene



Some of you obviously "get it." My hats off to 
you!Others, sadly, do not:

  -Original 
  Message-From: Dimitri Maziuk [mailto:[EMAIL PROTECTED]]Sent: Friday, November 30, 2001 17:53To: 
  debian-user@lists.debian.orgSubject: Re: Thoughts on RTFMGood. I 
  sincerely hope it'll stay there -- the last thing I want in my mailbox is 
  mail from lusers who need a dancing paper clip to tell them how to 
  insert a CD in the drive.
The last thing I do is let people like 
you define people like me.

  Definitely. If you 
  found DeadRat too hard, Debian is not for you. Maybe Linux is not for you. You 
  know, there's Mac Oh-SeX, several *BSDs, a bunch of 
  similar-but-not-entirely-unlike flavours of Winders out there, and more. Why 
  did you want to run Linux anyway? To be a k3w1 1337 h4X0r 
d00d?
My reasons for installing this distro are 
none of your business. If you can't help, stay out of the street.


Johnny Ernst Nielsen 
[EMAIL PROTECTED] wrote:

  Um, I see that particular question on and off on different lists. So you 
  better think again sir.
I stated that type of question 
rarely ever gets a polite reply. Thank-you for making my point.

  So, sir, you are simply not right.
Think so? The following 
was posted on debian-alpha. So far, no 
answers. I don't think it has anything to do with the question specifics. It 
seems to have everything to do with whether or not the question is sufficiently 
"interesting."
Hi:
 
On an 
AS/200, at the MILO prompt, I should be following these instructions, from the 
"Installing Debian GNU/Linux 2.2 for Alpha":

  
  To bootstrap the installation system, 
  enter the following command at the MILO prompt:  MILO> boot fd0:linux.gz root=/dev/fd0 load_ramdisk=1

  If you are booting from something other 
  than a floppy, substitute fd0 in the above example with the 
  appropriate device name in Linux notation. The help command would 
  give you a brief MILO command reference. 
Where is "linux.gz?" when 
I use the path "sr0:boot/linux.", MILO complains that this is not a gzipped 
file.
I would prefer not to install from floppies. Presumably I have a 
"bootable" CD-ROM image, although LSL disclaims any responsibility for the 
contents of the CD-ROM. 
 
It looks like even though I boot MILO, and can access a CD-ROM drive, I 
still have to rawrite & then boot from floppies to continue the 
installation? Perhaps linux.gz is 
the machine-specific image created by the install 
process?
 
I note that the section "Obtaining and 
Installing Linux" at www.linuxdoc.org 
doesn't actually mention this 
file.


Viktor Rosenfeld 
[EMAIL PROTECTED] (who does get it) 
wrote: 

  In fact, I think it's a very poorly worded 
  question, because it simply does not narrow down the problem space enough. 
  
Of course it's a poorly worded question: that's my point. There are so many 
failure modes that it's not possible to elucidate them all. Boasting about the 
quality of the documentation proves nothing to the rank beginner.

  Eg, one could include an error message that mount 
  gives, debugging information from the kernel, or if your newbie enough, not to 
  know that such information exists, you could describe that eg, the busy light 
  of the CD-ROM keeps flashing eratically, or that the drive makes funny noises, 
  and the like. If there's no such behavior, you should write that too, so some 
  options can be dismissed as possible sources for 
problems.
I added another CD-ROM at SCSI ID #4, leaving the failing drive at ID 
#5. From MILO, the command "ls -t iso9660 sr0:boot" succeeded, and the command 
"ls -t iso9660 sr1:boot" failed; error messages indicate that sr1: is unable to 
sense the presence of the disk.


Re: Thoughts on RTFM

2001-12-02 Thread Michael Heldebrant
On Sat, 2001-12-01 at 07:34, Tom Allison wrote:
> My point is this:
> If all you ever want is the step by step instructions, that is all you
> will ever know.



This is more or less the key for me to understanding why other people
can't be bothered to read the manual.  If it's not in a step by step
format for their exact problem they assume somewhere, someone else is to
blame for their problems.

The real solution is to understand that step by step instructions and
example config files are tools to properly comprehend the CONCEPTS and
their RELATIONSHIPS to the REQUIREMENTS to solve your PROBLEM.  Once you
learn what goals need to be accomplished and the steps needed to take
them, you don't need step by step instructions anymore.  You can map
your own route from point A to point B independent of a particular
howto.  Learning how to absorb massive amounts of Documentation and
incorporate the concepts ino your knowledge base is critical to
understanding where a particular point A and point B are for undefined
problems.  Sometimes some people get this very quickly, people like
Systems Analysts and Sysadmins usually, others often don't for a long
while.  The secret is not to know everything, but where to go looking
for it.

If you can't be bothered to read Documentation, you shouldn't be given
control over your own systems.  I'm really serious on this point, if you
don't want to learn how to fix it right you shouldn't ever try.  To the
people that say "That's why Linux will never be a desktop":  I agree,
the system is too complicated for most users, especially those who
expect and demand that a free product meet their expectations
immediately without trying to contribute anything but criticism.  There
is no one solution or default config, default enabling of unused
services is why Red Worm and things spread like wildfire through
Windows.  Linux can provide solutions to most tasks, you have to
understand what those are and why before you can implement them.

Of course those who do climb out of the newbie pit often look back and
see how obvious the solutions are to their old problems and figure
everyone should understand those now simple concepts, thats why I think
it's hard to write docs for newbies.

It doesn't help that most error messages are a tad bit cryptic to new
users and especially ones from Windows who only ever see a blue screen
and just shrug and reboot.  They've been trained to ignore why the
problem happened and not to look for the solutions.

Onto the main point of the thread.  The RTFM sayers aren't all lumped
into the same grouping.  I haven't seen all that much of a RTFM one
liner to a question much here, we actually care about users here.  The
other camp is trying to point someone in the right direction usually
after providing the solution or a large hint.

Self sufficiency as an admin is really the ultimate goal of helping list
questions here in my opinion.  When I see short questions that are
actually answerable by RTFM and it's someone relatively new I quote the
FM for them and tell them where I found it, suggestions to use the
command apropos to provide clues to the FM etc.

On the other hand if it's technical questions by experienced users I
recognize I answer them succinctly because I know that the answer will
provide understanding to the recpient independent of a lecture.

But, if people keep asking the same question after being given an
answer, or sometimes two or three that will work, or the answer is
RTFMLA (MLA=Mailing List Archives).  One ability that needs to be
learned is how to search for previous solutions from archives and
google.  Most questions I have have already been answered somewhere
else.  It gets annoying to see them same question over and over, and
over and over about 2 weeks later when the same issue hits testing from
unstable.



--mike



Re: Thoughts on RTFM

2001-12-02 Thread martin f krafft
* Peter Good <[EMAIL PROTECTED]> [2001.11.30 23:14:24+1000]:
> Hence why i'm subscribed to this list hehehehe, it's amazing the things i've 
> picked up over the past year, defintely helped my newbie status.

also a very good and very valid point.

now, peter, it's about time you start answering some! :)
no, i am not claiming that this is a "you-took-now-you-give" deal, but
in my specific case, i can very well remember the sudden increase in
gradient of my ability-curve as soon as i helped others. and if all
you can do right now is e.g. postfix, then help others with postfix.
that way, i promise, you are not only helping the debian project, you
are also pushing yourself further!

-- 
martin;  (greetings from the heart of the sun.)
  \ echo mailto: !#^."<*>"|tr "<*> mailto:"; [EMAIL PROTECTED]
  
windoze 98:  useless extension to a minor patch release for 32-bit
  extensions and a graphical shell for a 16-bit patch to an 8-bit
  operating system originally coded for a 4-bit microprocessor, written
  by a 2-bit company that can't stand for 1 bit of competition.


pgp3rNvsZoTzD.pgp
Description: PGP signature


Re: Thoughts on RTFM

2001-12-01 Thread Tom Allison

[EMAIL PROTECTED] wrote:

> I really don't want to single out Viktor Rosenfeld 
[EMAIL PROTECTED],

>  but his opinion is the pearl seed for a particular observation.
> Simultaneously, it represents the "rational" voice of most people
> who try to carry the stone, and is astonishingly wide of the mark.
> So:
>
>> [1] I don't really have anything against step-by-step
>> instructions, I've read a lot in my learning process and I've
>> written a couple of myself to help out others. I just think that
>> step-by-step instructions should serve as a base to familirize
>> (sp?) yourself with the problem. Once you get it going, you
>> should follow up some of the information.
>>
>
> This is the sort of Pollyanna Principle thinking that will keep
> Linux on the sidelines. For example, I just purchased the Debian
> distro from LSL. Guess what? They probably pressed it using
> multi-session CD format; which format my 5 yr. old SCSI CD-ROM
> drive won't read. RTFM is clearly not an answer: how will that
> answer solve a problem created by such an arbitrary decision by a
> vendor? No amount of "RTFM" is going to help here. No-one, on any
> list, is going to attempt to answer a question like: "I just bought
>  a CD and my computer won't read it. What's wrong?" And no, I
> haven't asked LSL in which format they burned the CD; such a
> question is likely to be met w/ shrugs, stares, and a lip curl that
>  could lift 10 stone.
>


I think that the conflict you are having is not the issue of RTFM, but
that you have been suckered into thinking that everything is too easy to
fix.
But it all depends on where you come from.
When you spend 6 years with Windows, the easiest fixes are those that
come from Windows - reinstall/reboot  kind of stuff.
But with other OSes, those options simply will not fix 90% of the
problems.  You're trying to compare a horse and a car.  Same road,
different engines!


I do have a specific example and point to all of this.

I had problems with my email.  Having used linux for 3 year (and no
Windows at all), I fired up a few goodies and diagnosed that the pop
server was not able to respond to my inquiries, though smtp server did.
That gave me the hypothesis, based on previous experience with email
servers with another ISP, that the email files where somehow corrupt for
my account only.
I called the ISP.
Two hours later, after stripping my entire network, firewall, rebooting
into Windows and outright trashing one PC, it was determined that there
was probably something wrong with the files on the email server.
The two hours was spent on going through the Windows-centric step by
step instructions on diagnosing the potential problems.  Unfortunately,
I didn't have a choice with the person I was talking to for her to
consider that I did RTFM and knew what I was talking about.
My point is this:
If all you ever want is the step by step instructions, that is all you
will ever know.
Windows is that same way - If someone asks me to help them set up a
Windows PC, I dump in the disks and click through the EULA's.  But if it
fails to work the first time - I walk away and tell them I can't fix it
unless it gives some *good* clues.
If I do the same thing with Debian, I have the option of at least
reading a manual that has enough information in it to help me diagnose
the problem.  This is true with ALL linux distributions.

But even in Windows, sometimes you will have to RTFM to get things to 
work.  If you don't think you do, then you are kidding yourself or have 
not had enough experience with Windows to hit this one yet.  Linux is 
the same basic way.  Keep in mind that a typical Windows installation 
does not include a web server, email server, and database server of the 
caliber that Linux does by default.  A more accurate comparison would be 
the Windows Server editions





Re: Thoughts on RTFM

2001-12-01 Thread Johnny Ernst Nielsen
> No-one, on any
> list, is going to attempt to answer a question like: "I just bought
> a CD and my computer won't read it. What's wrong?"

Um, I see that particular question on and off on different lists.
So you better think again sir.

> Tell me, [list], how would you phrase such a question so that it
> could be solved with "step-by-step instructions" that don't elicit
> the answer under discussion?

As others have said, many problems do not have a 
step-by-step-solution. It simply does not exists. So forget about it 
and approach the problem differently than asking for step-by-step 
help.

I'm not a total newbie, so I would also write what I have 
already attempted to do to get the darn thing to read the disc.
I do see the point. If I'm simply totally non-technical (like my 
mother) I will have no clue about what could be wrong and my question 
would be without any extra flesh on it.
But that doesn't mean that I won't get help.
When I see this question asked on lists, I also see replies that ask 
for specific information and/or comes with suggestions about what to 
try for starters.
If people really _want_ to be helped they will also go out of their 
way to work with the people that try to help them.
Seldomly do I see that the problem does not get solved, although at 
times it takes a long time because the user is not as techy as those 
who help.
But the point is that help is being given.

So, sir, you are simply not right.

Cheers :o)

Johnny :o)



Re: Thoughts on RTFM

2001-11-30 Thread Viktor Rosenfeld
Alan Shutko wrote:

> [EMAIL PROTECTED] writes:
> 
> > For example, I just purchased the Debian distro from LSL. Guess
> > what? 
> [...]
> > Tell me, [list], how would you phrase such a question so that it
> > could be solved with "step-by-step instructions" that don't elicit
> > the answer under discussion?
> 
> Well, you don't give enough information for anyone to help you but I'd
> suggest something like the following:
> 
>   I just bought a CD and my computer won't read it. What's wrong?  I
>   bought it from vendor X, and I've tried Y, Z, and can't think of
>   anything else.  I'm using a XYZZY CD-ROM drive on a Quantum Frobnitz
>   770.  Anybody know of common problems with this vendor or any other
>   possibilities?  Or somewhere else I could look for help?  How could
>   I try to trace this down further?
> 
> It would probably yield a few different answers, including some
> step-by-step tips on narrowing down the cause of the failure.

Right on!

Jeff, you're right when you believe that I would generally not answer a
question like "I just bought a CD and my computer won't read it. What's
wrong?".

In fact, I think it's a very poorly worded question, because it simply
does not narrow down the problem space enough.  Eg, one could include
an error message that mount gives, debugging information from the
kernel, or if your newbie enough, not to know that such information
exists, you could describe that eg, the busy light of the CD-ROM keeps
flashing eratically, or that the drive makes funny noises, and the like.
If there's no such behavior, you should write that too, so some options
can be dismissed as possible sources for problems.

I mean, you're the one sitting in front of the damn computer and if you
blindfold us by not giving any relevant information, how are we supposed
to help you?

Especially with a problem like this, which I think is rather unheard of.
As the part about your friends, who's probably just guessing here,
shows: The only way you'll get a answer that solves your problem, is
when someone who once stumbled upon the same problem, recognizes the
symptoms and tells you what he did to make it right.  This is impossible
with the question you've asked!  We all had our share of unrecognized
CDs, with numerous sources of conflicts, *anything* could be wrong with
the CD and/or your setup.

(E.g. I once had a problem, when a old 4speed CD-ROM drive would not
recognized parts of my slink (Debian 2.0) distribution CD, which worked
fine on another machine.  I "solved" the problem, by using the disk set
from a friend, however the drive is now much broken, eg. it won't boot
CDs anymore and fails on a lot of CDs, so I think that my problem with
this particular CD was actually broken hardware.  This could be your
problem as well, but how am I supposed to know?)

Besides, you probably *will* get answers on your question, like "Did you
do XYZ?  Try ABC!  What does SomeMagicTool say, when you try
VeryMysticalProcedure?  Are you sure that the Thingi on your drive is
working properly?"  This is as helpful as one can get in this situation.

Alan gave some wonderful examples, how to narrow down the problem, if
this is not helpful, what are you looking for?  A magic cristal ball?

Cheers,
Viktor

PS: I think, that you mistake would I meant regarding step-by-step
instructions, but I'll save that to another post.

PPS: It's 4:30am and I'm rather stoned, so if my post sounds incoherent
or even offensive, please don't take it as this.

PPPS: I thought it impossible, loosing a (potential) Debian user to
RedHat.  This just doesn't sound right, IMNSHO.
-- 
Viktor Rosenfeld
WWW: http://www.informatik.hu-berlin.de/~rosenfel/


pgp39qwdbiYdi.pgp
Description: PGP signature


Re: Thoughts on RTFM

2001-11-30 Thread dman
On Fri, Nov 30, 2001 at 06:52:57PM -0600, Dimitri Maziuk wrote:
| * [EMAIL PROTECTED] ([EMAIL PROTECTED]) spake thusly:
| ...
| > This is the sort of Pollyanna Principle thinking that will keep Linux on the
| > sidelines. 
| 
| Good. I sincerely hope it'll stay there -- the last thing I want 
| in my mailbox is mail from lusers who need a dancing paper clip 
| to tell them how to insert a CD in the drive. 

apt-get install vigor

you'll get a good laugh

| Dima (non-technical user is the one who wrote only one device driver)

I like this quote (I've seen it before), but the rest of it should be
included :

"""
"...In the UNIX world, people tend to interpret `non-technical user' as
meaning someone who's only ever written one device driver."
--Daniel Pead
"""

-D

-- 

"GUIs normally make it simple to accomplish simple actions and
impossible to accomplish complex actions."
--Doug Gwyn  (22/Jun/91 in comp.unix.wizards)



Re: Thoughts on RTFM

2001-11-30 Thread Dimitri Maziuk
* [EMAIL PROTECTED] ([EMAIL PROTECTED]) spake thusly:
...
> This is the sort of Pollyanna Principle thinking that will keep Linux on the
> sidelines. 

Good. I sincerely hope it'll stay there -- the last thing I want 
in my mailbox is mail from lusers who need a dancing paper clip 
to tell them how to insert a CD in the drive. 

... I gave up on Red Hat, because of their
> bogus RPM, and utter lack of competent technical support. Throwing myself
> into the Debian mosh pit is beginning to look like an even worse mistake.

Definitely. If you found DeadRat too hard, Debian is not for you. 
Maybe Linux is not for you. You know, there's Mac Oh-SeX, several 
*BSDs, a bunch of similar-but-not-entirely-unlike flavours of 
Winders out there, and more. Why did you want to run Linux anyway? 
To be a k3w1 1337 h4X0r d00d?

Dima (non-technical user is the one who wrote only one device driver)
-- 
Q276304 - Error Message: Your Password Must Be at Least 18770 Characters
and Cannot Repeat Any of Your Previous 30689 Passwords   -- RISKS 21.37



Re: Thoughts on RTFM

2001-11-30 Thread Alan Shutko
[EMAIL PROTECTED] writes:

> Simultaneously, it represents the "rational" voice of most people
> who try to carry the stone, and is astonishingly wide of the
> mark.

I'm having trouble finding your point.  Maybe you could clarify it?
Is it that you think that nobody would ever say more than "RTFM" or
that you don't think anyone should try to learn more than is given in
step-by-step instructions?

> For example, I just purchased the Debian distro from LSL. Guess
> what? 
[...]
> Tell me, [list], how would you phrase such a question so that it
> could be solved with "step-by-step instructions" that don't elicit
> the answer under discussion?

Well, you don't give enough information for anyone to help you but I'd
suggest something like the following:

  I just bought a CD and my computer won't read it. What's wrong?  I
  bought it from vendor X, and I've tried Y, Z, and can't think of
  anything else.  I'm using a XYZZY CD-ROM drive on a Quantum Frobnitz
  770.  Anybody know of common problems with this vendor or any other
  possibilities?  Or somewhere else I could look for help?  How could
  I try to trace this down further?

It would probably yield a few different answers, including some
step-by-step tips on narrowing down the cause of the failure.

I find it interesting that you believe that nobody, on any list, would
try to answer a question of that ilk.  It's also interesting that you
have decided not to ask your vendor about the problems you are seeing,
since they would be best situated to help you.  Instead you choose to
believe a random explanation by a co-worker, 

As far as that explanation, I believe it unlikely.  I can't think of
any reason LSL would use multisession CDs.  (I suppose they could do
it so they could reuse CDs from an older Debian, but I don't think
there would be room.)  It's far more likely that the CD is just bad,
or if they're sending CDR media instead of silver discs, that the CDR
media they used is one which your drive has problems with.  That's a
fairly common problem among old drives, and still persists in some new
drives.  Some CDRs will work fine in a drive, other types won't.

It seems to be as if your determined not to let people help you, so
that may be why you have trouble finding help.

> It's not even *remotely* possible to "familirize (sp?) yourself" with a
> problem like incompatible CD formats. 

That's patently untrue.  People do it every day, especially now that
more people are sending things like photo albums to each other on CD.  

-- 
Alan Shutko <[EMAIL PROTECTED]> - In a variety of flavors!
If you knew what to say next, would you say it?



Re: Thoughts on RTFM

2001-11-30 Thread Jeff . Chimene
I really don't want to single out Viktor Rosenfeld
[EMAIL PROTECTED], but his opinion is the pearl seed for a
particular observation. Simultaneously, it represents the "rational" voice
of most people who try to carry the stone, and is astonishingly wide of the
mark. So:
> [1] I don't really have anything against step-by-step instructions, I've
> read a lot in my learning process and I've written a couple of myself to
> help out others. I just think that step-by-step instructions should
> serve as a base to familirize (sp?) yourself with the problem. Once you
> get it going, you should follow up some of the information.

This is the sort of Pollyanna Principle thinking that will keep Linux on the
sidelines. For example, I just purchased the Debian distro from LSL. Guess
what? They probably pressed it using multi-session CD format; which format
my 5 yr. old SCSI CD-ROM drive won't read. RTFM is clearly not an answer:
how will that answer solve a problem created by such an arbitrary decision
by a vendor? No amount of "RTFM" is going to help here. No-one, on any list,
is going to attempt to answer a question like: "I just bought a CD and my
computer won't read it. What's wrong?" And no, I haven't asked LSL in which
format they burned the CD; such a question is likely to be met w/ shrugs,
stares, and a lip curl that could lift 10 stone.

Tell me, [list], how would you phrase such a question so that it could be
solved with "step-by-step instructions" that don't elicit the answer under
discussion? RTFM is *not* an option. It's a rude, elitist opinion that has
no shortage of clueless technocrats willing to fill the airwaves with that
meaningless answer. There are so *many* things that can go wrong trying to
install any Linux distro that the simplistic "RTFM - now go away"  is
nothing short of technical infanticide. It sounds funny to the dittoheads
who parrot the Hacker's Dictionary, but will never help carry the stone. The
sui generis proposition: "Once you get it going" is an unsustainable
directive to all but the earnest propeller-head.

It's not even *remotely* possible to "familirize (sp?) yourself" with a
problem like incompatible CD formats. I gave up on Red Hat, because of their
bogus RPM, and utter lack of competent technical support. Throwing myself
into the Debian mosh pit is beginning to look like an even worse mistake.

FWIW, the CD format clue was suggested by a co-worker; it sounds just
plausible enough to be true.



Re: Thoughts on RTFM

2001-11-30 Thread Karsten M. Self
on Thu, Nov 29, 2001 at 10:46:15PM -0400, cmasters ([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

This depends on how RTFM is used.

My own invocation of the incantation is a shorthand of the longer
phrase:

The information you seek is documented.  It's part of the standard
document set which should have been included on your system, and is
certainly available for installation if you select the proper
packages (ping back for more information).  Recognizing that the
documentation is voluminous, and not immediately accessible to
newcomers, I'll even provide you with a pointer to the proper page.
Please read the information contained therein, and report back to
the list if you have further questions.

The documents you seek are XXX.

It's a lot easier to just write:

RTFM XXX

...where XXX is the page in question.

The "naked RTFM" is neither helpful nor encouraged.  Criticising its use
is fully merited.



In the immortal words of a former roommate of mine, Dave (not to be
confused with my other roommate at the time, Dave, or his friend Dave,
or Dave's friend Dave, a prior roommate Dave, or two subsequent
roommates named "Dave",  or (back to the Dave in question) Dave's friend
Dave who called one time asking if Dave was in, requiring me to ask
Dave's friend Dave if he knew, and resulting in my response, "Dave, I'm
sorry, but Dave's friend Dave says Dave's not here right now[1]".  This was
understood perfectly), concerning the location of some household item:

   You're an adult.  Look for it.


That's right.  GNU/Linux is an OS for mature adults.  Note that that's
"mature adults", not "smug asspricks".  Post here indicating you're
having trouble, clues will be distributed.  Follow up with "OK, I tried
that, and it didn't work", with appropriate documentation of _exact
commands tried_ and _exact error messages or diagnostics received_, and
you'll likely get more assistance.  However, RTFM, RTFS, and STFW
(search the fine web) are perfectly acceptable responses.


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

If this is what your instructor is telling you, s/he's a smug assprick.

The proper thing for the instructor to do is to _serve as a guide
through the wilderness_.  Just dumping a bunch of data on your lap is
not teaching or guidance.  A syllabus and/or study guide would be
minimum expectations.



<...> 

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

No, but you should be pointed to appropriate texts for getting started.



<...> 

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

This is a frequent failing of GNU/Linux and UNIX documentation.
Manpages without examples should be considered bugs.  You have my
sympathies here.

In the meantime, it's appropriate to post a statement "I researched foo
in the Mutt docs and don't know the proper syntax to be used to set the
value(s) specified".



Peace.


Notes:

1.  Yes, that's the absolute truth.  I'm glad I'm named Karsten.

-- 
Karsten M. Selfhttp://kmself.home.netcom.com/
 What part of "Gestalt" don't you understand? Home of the brave
  http://gestalt-system.sourceforge.net/   Land of the free
   Free Dmitry! Boycott Adobe! Repeal the DMCA! http://www.freesklyarov.org
Geek for Hire http://kmself.home.netcom.com/resume.html


pgpmuufEavChq.pgp
Description: PGP signature


Re: Thoughts on RTFM

2001-11-30 Thread Kirk Strauser

At 2001-11-30T15:52:18Z, Viktor Rosenfeld <[EMAIL PROTECTED]> writes:

> Unfortunately, I also had my fair share of people, who just wanted total
> step-by-step instructions, didn't care for the information I gave them,
> asked follow-up question, that showed, that they haven't put a single
> thought into the problem themselves and generally just wanted me to come
> over and solve the problem for them.  This attitude is frustrating and if
> it hits me too often, I invoke the RTFM.

I concur.  I'm really not a good instructor; I have a hard time taking n
streams of information and verbally spewing out 1 coherent list of
instructions to execute a task.  However, I'll do my best to help someone
learn something, *if* they can be bothered to try to participate in the
experience.  I steadfastly refuse to answer question after question when the
answers should be readily apparent to someone who tried to understand the
original answer.

  User: "How do I see all of the JPEGs in a directory?"
  Me: "The ls command gives you a list of files.  Type ls *.jpg ."
  User, 10 minutes later: "How do I see all of the GIFs in a directory?"
  Me: "man ls"

I realize that I've been blessed with the ability to absorb huge amounts of
documentation, and that not everyone shares this trait.  Still, I'm a lot
more likely to give assistance if the person asking will at least *try* to
learn for themselves.
-- 
Kirk Strauser



Re: Thoughts on RTFM

2001-11-30 Thread Viktor Rosenfeld
Hi Bud,

Bud Rogers wrote:

> Some linux newbies are lucky enough to find an elmer to help them get 
> started.  I was.  He spent hours on the phone with me, talking me 
> through my first install of Slackware in the summer of 1995.  He spent 
> more hours on email and ytalk helping me customize and secure my system.  
> He answered every one of my ignorant newbie questions.  He never once 
> invoked the dreaded RTFM.  But every answer came with a reference.  He 
> would give me a short answer to my question along with a pointer to a 
> HOWTO or web page where I could find the long answer.  I always followed 
> his pointers.  I read the docs he pointed me to.  His short answers got me 
> over the hurdles quickly, and the pointers filled in my ignorance. And the 
> combination brought me up to speed very fast.  In about five months I went 
> from absolute newbie to sysadmin of a local startup ISP.  That's no brag 
> on me.  Most of the credit goes to my elmer.

To me it sounds, like not only you got lucky, but so got your elmer.

I found it a joy to help out a couple of friends who are genuinly
interested in Linux and would really read up on the information I've
given them.  And if you feel that your help is truly appreciated and
respected, then helping almost comes natural.

Unfortunately, I also had my fair share of people, who just wanted total
step-by-step[1] instructions, didn't care for the information I gave
them, asked follow-up question, that showed, that they haven't put a
single thought into the problem themselves and generally just wanted me
to come over and solve the problem for them.  This attitude is
frustrating and if it hits me too often, I invoke the RTFM.

So, my point here is that these communities (the ham community you
described, and the linux users) need a high level of mutual respect and
willingness.  Both the newbies and oldies must be willing to spend some
time and effort to improve the community and if they don't it gets
frustrating.  Eventually the community breaks apart.

[1] I don't really have anything against step-by-step instructions, I've
read a lot in my learning process and I've written a couple of myself to
help out others.  I just think that step-by-step instructions should
serve as a base to familirize (sp?) yourself with the problem.  Once you
get it going, you should follow up some of the information.

Ciao,
Viktor
-- 
Viktor Rosenfeld
WWW: http://www.informatik.hu-berlin.de/~rosenfel/


pgpGshVGO26Fa.pgp
Description: PGP signature


Re: Thoughts on RTFM

2001-11-30 Thread Peter Good
Hence why i'm subscribed to this list hehehehe, it's amazing the things i've 
picked up over the past year, defintely helped my newbie status.

Peter.


On Fri, 30 Nov 2001 15:00, dman wrote:
> On Thu, Nov 29, 2001 at 11:41:39PM -0500, Alan Shutko wrote:
> [lots of good comments]
>
> I must say that Alan has done a better job of describing the situation
> than I did.  I too have found it very useful (and enjoyable) to read
> docs that seem interesting, yet I often don't understand or have a use
> for much of it at the time.  Then sometimes I remember having seen
> something somewhere and I know what to look for when the situation
> arises.
>
> -D



Re: Thoughts on RTFM

2001-11-30 Thread George Karaolides

Have a look at RUTE (Rute User's Tutorial and Exposition) at

http://rute.sourceforge.net

It's available as a book, but being GPL'd it's also available for free
download.  Being GPL'd also means it's open to your contributions.

It'll tell you everything you always wanted to know but everyone assumed
you knew already.

Debian package of rute, anyone?

Best regards,

George Karaolides   8, Costakis Pantelides St.,
tel:   +35 79 68 08 86   Strovolos,
email: [EMAIL PROTECTED]   Nicosia CY 2057,
web:   www.karaolides.com  Republic  of Cyprus



On Thu, 29 Nov 2001, cmasters 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
>
> 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.
>
> 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.
>
> 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.
>
> 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.
>
> 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".
>
> All for now,
>
> C. Masters
>
>
> --
> To UNSUBSCRIBE, email to [EMAIL PROTECTED]
> with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
>



Re: Thoughts on RTFM

2001-11-30 Thread Bud Rogers
On Thursday 29 November 2001 23:31 pm, Paolo Falcone wrote:

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


Paolo, I think you have hit upon a key point.  The whole RTFM mentality 
reflects as much on the RTFMers as it does on the newbies.

Long before I had anything to do with Linux I was into amateur radio.  The 
ham community has a lot in common with the Linux community.  There is a 
strong do-it-yourself ethic.  The community is mostly self-policing.  Hams 
who violate FCC regulations usually get hammered by other hams long before 
the FCC notices.

But there is also a long, strong tradition of helping beginners get 
started.   Every ham knows there is a short steep learning curve just to 
put a station on the air.  Every ham knows a novice is likely to pollute 
the airwaves with a few unintended radiations in the process of gettting 
started.  Every ham remembers the excitement and the difficulty of getting 
over those first few hurdles.  Most hams are willing to help a novice get 
started.  Most will answer questions if asked.  Many will go out of their 
way to help a newbie get started.  Some are more willing than others, and 
some are more able than others.  The few who are most willing and best 
able to help a novice get started are known as elmers.  Every ham has fond 
memories of some elmer who helped him get started.

Some linux newbies are lucky enough to find an elmer to help them get 
started.  I was.  He spent hours on the phone with me, talking me 
through my first install of Slackware in the summer of 1995.  He spent 
more hours on email and ytalk helping me customize and secure my system.  
He answered every one of my ignorant newbie questions.  He never once 
invoked the dreaded RTFM.  But every answer came with a reference.  He 
would give me a short answer to my question along with a pointer to a 
HOWTO or web page where I could find the long answer.  I always followed 
his pointers.  I read the docs he pointed me to.  His short answers got me 
over the hurdles quickly, and the pointers filled in my ignorance. And the 
combination brought me up to speed very fast.  In about five months I went 
from absolute newbie to sysadmin of a local startup ISP.  That's no brag 
on me.  Most of the credit goes to my elmer.

Thank you, jjohn.  Thank you.

-- 
Bud Rogers <[EMAIL PROTECTED]>
All things in moderation.  And not too much moderation either.



Re: Thoughts on RTFM

2001-11-30 Thread Bud Rogers
On Thursday 29 November 2001 22:28 pm, Charles Baker wrote:
> <>
> 
> > > >  apt-get install linuxcookbook
> > I just tried the above using source.list entries for
> > stable, and it
> > wasn't downloaded:
 
> I just got in, but I'm using unstable.

And I'm apt-getting it from woody as I type.

-- 
Bud Rogers <[EMAIL PROTECTED]>
All things in moderation.  And not too much moderation either.



Re: Thoughts on RTFM

2001-11-30 Thread Osamu Aoki
On Thu, Nov 29, 2001 at 10:46:15PM -0400, cmasters wrote:
> Greetings all,
Greetings. 
> My recent difficulties with printer and mail setup have led to to the point
> where I simply must express my thoughts on "RTFM".

RTFM is easy.  If you stack with Linux, sometimes best answer is RTFS
with S standing for Source.

Most FAQ and HOWTO are out dated.  Just a fine hints but not a serious
defenitive reference in many cases unless upstrean software authou
maintain it diligently (exim is a one with fine manual.)

Some kernel things have no documentation other than one in the Source.

Anyway nothing is free(beer).  Time and effort of users are demanded.
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ 
+  Osamu Aoki <[EMAIL PROTECTED]>, GnuPG-key: 1024D/D5DE453D  +
+  My debian quick-reference, http://qref.sourceforge.net/quick/   +



Re: Thoughts on RTFM

2001-11-29 Thread Mike Pfleger
* Alan Shutko ([EMAIL PROTECTED]) wrote:
 
> It's likely that their situation is not identical to yours.  Some
> people learn better in this way than others.  When I began learning
> Linux, I simply read all the available documentation and pieced things
> together where I could.  In fact, I'd read all the available howtos
> before I even installed Linux, because I hadn't yet gotten my machine.
> (I did the same thing with C, for a similar reason.)
> 
> I do well at this sort of thing: taking large quantities of material
> and putting things together.  It's hard for me to explain things in a
> clear and linear fashion, because understanding came for me in an
> instant of connecting seven different things, and I have trouble
> expressing myself in other ways.
> 
> I don't want to sit here and say "I am better than you" but more "I am
> different from you, and your experiences are important."  You are much
> better situated to identify and correct problems with documentation so
> that others who learn things as you do can benefit.  It's hard to do
> so, but very worthwhile.


Hi Alan.

It's always nice to read a positive and helpful reply in such a thread.
I commend you for your clarity and understanding on these points, and
wish more people responded this way.

I've certainly had my share of flailings in my computer adventures ;)

Cheers,
Mike Pfleger
[EMAIL PROTECTED]
(250) 479-0321



Re: Thoughts on RTFM

2001-11-29 Thread Paolo Falcone

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

Re: Thoughts on RTFM

2001-11-29 Thread Gary Turner
On Thu, 29 Nov 2001 23:41:39 -0500, you wrote:

>cmasters <[EMAIL PROTECTED]> writes:
>
>> 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. 


Dman and Alan,

You both have made excellent points.  Man pages targeted at the newbie
would drag everything down.  If the more common commands/files were to
include concrete examples illustrating the more important options and
their results, then folks like myself could better understand.  Maybe
there's a bug in my cpu instruction set, but I learn new stuff much
better going from concrete to abstract.

It's not necessary to go back to square one each time.  Just a quick
example to tie 50-100 hardcopy pages together, leaving out the esoteric
and arcane would do it.  Esoteric and arcane commands are exempt .

gt
Yes I fear I am living beyond my mental means--Nash



Re: Thoughts on RTFM

2001-11-29 Thread dman
On Thu, Nov 29, 2001 at 11:41:39PM -0500, Alan Shutko wrote:
[lots of good comments]

I must say that Alan has done a better job of describing the situation
than I did.  I too have found it very useful (and enjoyable) to read
docs that seem interesting, yet I often don't understand or have a use
for much of it at the time.  Then sometimes I remember having seen
something somewhere and I know what to look for when the situation
arises.

-D

-- 

(E)ventually (M)alloc()s (A)ll (C)omputer (S)torage



Re: Thoughts on RTFM

2001-11-29 Thread Alan Shutko
cmasters <[EMAIL PROTECTED]> writes:

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

Remember that most of the people who tell others to RTFM are people
who _have_ bootstrapped themselves from no knowledge with the same, or
less, documentation as you have before you.  I'm one of them.

It's likely that their situation is not identical to yours.  Some
people learn better in this way than others.  When I began learning
Linux, I simply read all the available documentation and pieced things
together where I could.  In fact, I'd read all the available howtos
before I even installed Linux, because I hadn't yet gotten my machine.
(I did the same thing with C, for a similar reason.)

I do well at this sort of thing: taking large quantities of material
and putting things together.  It's hard for me to explain things in a
clear and linear fashion, because understanding came for me in an
instant of connecting seven different things, and I have trouble
expressing myself in other ways.

I don't want to sit here and say "I am better than you" but more "I am
different from you, and your experiences are important."  You are much
better situated to identify and correct problems with documentation so
that others who learn things as you do can benefit.  It's hard to do
so, but very worthwhile.

Here are some suggestions on making your path (hopefully) easier, and
pointing out problems you discover:

* Try to read in a less directed fashion.  Read documentation for
  which you have no immediate purpose.  Don't focus on trying to
  understand everything, or even much of anything.  The mere act of
  familiarizing yourself with the material will help you later on when
  you _do_ have a goal.  You may remember something that now makes
  sense to you, or at least remember that something can be done.

* When researching for an active goal, write down or remember somehow
  exactly what problems you find.  If you have a problem finding
  something in a manual, that's a bug in the manual.  Report it, and
  explain specifically what's wrong.  It probably looks completely
  clear to the person who wrote it, because they have context that you
  don't.  Your experience as someone without that context makes your
  input important.

* When asking questions, ask for specific pointers in the manuals, and
  explain where you've looked for other answers.  It may be that a
  person telling you to RTFM _thinks_ that the answer is somewhere in
  the manual, but is recalling incorrectly.  (It's happened to me more
  times than I can count.)  Clear communication will help identify
  these problems.

I hope this message is at least a little helpful.

-- 
Alan Shutko <[EMAIL PROTECTED]> - In a variety of flavors!
What happens when you cut back the jungle?  It recedes.



Re: Thoughts on RTFM

2001-11-29 Thread Charles Baker

<>

> > >  apt-get install linuxcookbook
> I just tried the above using source.list entries for
> stable, and it
> wasn't downloaded:
> 
> inneal:~# apt-get install linuxcookbook
> Reading Package Lists... Done
> Building Dependency Tree... Done
> E: Couldn't find package linuxcookbook
> inneal:~# apt-cache search linuxcookbook
> inneal:~# 
> 
> If there was a different spelling or something
> please let me know.  I'd
> like to get this document.
> 
<>

I just got in, but I'm using unstable.


=
-
[EMAIL PROTECTED]
Hacking is a "Good Thing!"
See http://www.tuxedo.org/~esr/faqs/hacker-howto.html

__
Do You Yahoo!?
Yahoo! GeoCities - quick and easy web site hosting, just $8.95/month.
http://geocities.yahoo.com/ps/info1



Re: Thoughts on RTFM

2001-11-29 Thread Xeno Campanoli
Ian Monroe wrote:
> 
> A surprising about information is still locked up in books. Though some
> are availible online, checking out your local huge bookstore is a good
> idea.
> 
> Ian Monroe
> http://mlug.missouri.edu/~eean/
> 
> On Thu, 29 Nov 2001, Lance Simmons wrote:
> 
> > A book that's full of useful examples is _The Linux Cookbook_ by Michael
> > Stutz, available in paperback from Linux Journal Press, and also by
> >
> >  apt-get install linuxcookbook
I just tried the above using source.list entries for stable, and it
wasn't downloaded:

inneal:~# apt-get install linuxcookbook
Reading Package Lists... Done
Building Dependency Tree... Done
E: Couldn't find package linuxcookbook
inneal:~# apt-cache search linuxcookbook
inneal:~# 

If there was a different spelling or something please let me know.  I'd
like to get this document.

> >
> > Another extremely useful book for getting the whole unix thing is _Think
> > Unix_ by Jon Lasser (QUE, 2000)
> >
> > --
> > Lance Simmons
> >
> 
> --
> To UNSUBSCRIBE, email to [EMAIL PROTECTED]
> with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

-- 
http://www.eskimo.com/~xeno
[EMAIL PROTECTED]



Re: Thoughts on RTFM

2001-11-29 Thread dman
On Thu, Nov 29, 2001 at 10:46:15PM -0400, cmasters 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".
...
| 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.
...
| 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. 

Certainly there are conventions that are used by unix users, and it
certainly helps to know these when reading various manuals.  There are
books (and I'm sure howtos or other docs) that explain the basics of a
shell, filesystem, and other conventions.  However you don't want
_every_ manual written for the _complete_ newbie.  If they were, they
would all have the same basic here's-how-you-turn-it-on,
here's-how-you-name-the-files, etc., etc., in them and that would
unnecessarily bloat the manual and make it a chore to find the real
information.  Certainly complete newbies need some assistance to learn
the basics, but that should be in a dedicated document.  Once you've
read a couple of howtos or manuals, you get a feel for how they read.
In addition, there is no better teacher than experience.

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

If you note, section 6 is the _Reference_ section.  References are
meant to be short and to the point without examples.  They are
intended for those who know what they are doing, but need to refresh
their mind on a point or two.  Also, section 6.3 is the _Configuration
Variables_ section, not the _Configuration Commands_ section (6.2).
All of them need "set".

| I actually fully support it (hence my
| refusal to cave-in and use M-crap).

That's cool.

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

Isn't that what this list is for?  (only semi-serious)

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

True, but all of it is dependent on volunteer effort.  If I like
coding and don't like writing docs, it is less likely that I'll spend
my free time writing docs than coding.  It is also probable that my
docs are not very good.  Also, every document needs an audience.  If I
expect my audience to be well educated and understand common unix-ism
and/or conventions, then I will not explain them as if they didn't.
My perspective on who will be using my code also makes a difference in
the type and style of the docs I write.


After all this, I must admit that when I read through the procmail
manpages I didn't understand most of it.  I did end up determining the
pattern that I should follow for the types of rules I write, and I
know that there is much, much more power there if I really want to
learn it.

-D

-- 

Microsoft: "Windows NT 4.0 now has the same user-interface as Windows 95"
Windows 95: "Press CTRL-ALT-DEL to reboot"
Windows NT 4.0: "Press CTRL-ALT-DEL to login"



Re: Thoughts on RTFM

2001-11-29 Thread Ian Monroe
A surprising about information is still locked up in books. Though some
are availible online, checking out your local huge bookstore is a good
idea.

Ian Monroe
http://mlug.missouri.edu/~eean/

On Thu, 29 Nov 2001, Lance Simmons wrote:

> A book that's full of useful examples is _The Linux Cookbook_ by Michael
> Stutz, available in paperback from Linux Journal Press, and also by 
> 
>  apt-get install linuxcookbook
> 
> Another extremely useful book for getting the whole unix thing is _Think
> Unix_ by Jon Lasser (QUE, 2000) 
> 
> -- 
> Lance Simmons
> 



Re: Thoughts on RTFM

2001-11-29 Thread Lance Simmons
A book that's full of useful examples is _The Linux Cookbook_ by Michael
Stutz, available in paperback from Linux Journal Press, and also by 

 apt-get install linuxcookbook

Another extremely useful book for getting the whole unix thing is _Think
Unix_ by Jon Lasser (QUE, 2000) 

-- 
Lance Simmons



Re: Thoughts on RTFM

2001-11-29 Thread Kurt Lieber
On Thursday 29 November 2001 06:46 pm, cmasters wrote:
> 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".

There definitely is a strong elitist mentality among many linux folks, but 
not all of them.  There are also some strong newbie documentation projects 
that are underway as well:

http://newbiedoc.sourceforge.net/
http://www.linuxnewbie.org/
http://www.debianhelp.com/

are a few that spring to mind.  The newbiedoc project on sourceforge helped 
me immensely as I was learning how to compile a new kernel the debian way.

You're absolutely right -- the bar needs to be lowered a couple notches, at 
least on the documentation side of things.  The great thing is that you can 
pick up your cause and run with it.  Join one of the projects above and help 
them make newbie documentation that much better.  Or, if you feel so 
inclined, start your own. (I personally discourage this since I feel another 
problem with linux documentation it that it's scattered across the four winds)

Also, rest assured that, with a little determination and perseverance, you 
*can* learn this stuff.  It's not as easy to learn as windows, no, but it's 
also far, far more flexible, so it's a tradeoff.

Anyway, my $.02.

--kurt

P.S. I can't imagine learning linux in the pre-internet days.  I think it 
would be almost impossible unless you had a pre-existing group of 
linux-geek-buddies.