From: jlg@cochiti.lanl.gov (Jim Giles)
Newsgroups: comp.lang.c
Subject: Re: About the 'F' in RTFM
Date: 12 Aug 92 17:17:48 GMT
Article-I.D.: newshost.1992Aug12.171748.26339
Organization: Los Alamos National Laboratory

In article <1992Aug11.211023.29074@mksol.dseg.ti.com>, mccall@mksol.dseg.ti.com (fred j mccall 575-3539) writes:
|> In <1992Aug10.161448.1284@newshost.lanl.gov> jlg@cochiti.lanl.gov (Jim Giles) writes:
|> [...]
|> >Let me get this straight.  You actually _read_ every word of every
|> >document [...]?  
|> [...]                                            Bletch.  You 
|> >have a higher tolerance for badly written prose that I do.  
|> 
|> Well, I certainly do.  I read it at least once, so I'm at least aware
|> of what the default behaviour IS.  Bletch, perhaps, but I find that
|> it's much easier to write software that works if I know how the things
|> it is build on top of work.

Your approach is faulty for three reasons.  First, the document doesn't
tell you *how* the thing works, only *what* it's *supposed* to do.  
Second, what it's supposed to do often doesn't match what it does.  
Third, as badly as the documents are written, it's more cost effective 
to have *one* person read them and have everyone else ask!  You want 
people to stop asking - write better manuals - they'll *voluntarily* 
stop asking and read the new manuals instead.

|> [...]
|> >Further, as I said before, the default behavior of something should 
|> >be _completely_ covered before the first optional parameter is even 
|> >introduced.  You should not have to read *ANY* of the documentation 
|> >for the *OPTIONS* in order to understand the default behavior.  You 
|> >should not have to read other documents either.
|> 
|> Nonsense!  I would go absolutely crazy reading a document that
|> specified 30 different default behaviour options before it explained
|> what those options were and how to set them.  The documentation makes
|> more sense if the options are explained and the default values given
|> in the same place: the listing of options.

This is exactly contrary to the *supposed* advantage of the UNIX 
environment: "each tool does *one* simple thing and does it well."  
Your statement is an admission that this *supposed* advantage is 
nonsense (I knew that already, but in the past I've not found UNIX
supporters who would admit it).  If the UNIX `philosophy' was actually 
followed, it would be trivially easy to document the default (and 
*only*) behavior of each tool.  The fact is, the design philosophy 
of having lots of simple tools has *some* merit - especially if the 
tools are mutually consistent and easy to use together.  It's just 
that this is not *really* how the UNIX environment is designed (the 
tools aren't simple and they have lots of subtle incompatibilities).

In the meantime, options should be *optional*!  You should not have to 
know *anything* about the options you don't use.  If you do have to know
about them, then the tool or the document or *both* are badly designed.
Even if you *read* the documents entirely, the fact that a behavior was
described only in the `options' section may mislead you into believing
the behavior is not performed by default.

|> [...]
|> Perhaps you should get a job working in a different environment, if
|> you find UNIX so terrible to use?  

You show me a place where I've got a choice, and I'll go there like 
a shot.  UNIX is promoted for advantages it doesn't have (like its 
supposedly user friendly environment), the management signs off on it, 
and there's nothing the technical staff can do about it.

|> [...]
|> >You ignored what I said.  It is more cost effective to ask rather
|> >than to look it up.  This is true regardless of the nature of the
|> >question.  If you don't like that, the quality of the documentation
|> >is to blame, not those who ask the questions.
|> 
|> This is only true when it is on a 'single time' basis.  At some point,
|> you have to learn to find your own answers and stop wasting the time
|> of people who have more important things to do with their expertise
|> than answer questions that are easily answered by referring to the
|> manual. 

*MOST* users have more important things to do than waste their time 
reading UNIX manuals.  After all, the content of these manuals is not 
*real* knowledge, it's arcane information about interfaces that someone 
*arbitrarily* invented (without even bothering to do any human-factors 
studies first).  The fact is that if everyone started reading the manuals 
instead of asking, the overall productivity of your company would *decrease*.
I don't think your management would appreciate such a change.

When people ask me questions, I answer them. <- Period.  If they complain
about the quality of the manuals, I agree with them (I found them nearly
incomprehensible when I first read them too).  I don't recommend that 
*anyone* read the manuals except as a last resort (that is, when no one
is available to *ask*).  In fact, if you tell the user which manual is
appropriate, they usually *will* try to read it - and the resulting 
questions (to explain the manual) will usually take longer than if 
you just explained the tool to them to begin with.

-- 
J. Giles