From: mccall@mksol.dseg.ti.com (fred j mccall 575-3539)
Subject: Giles' Manual Mania (Was - Re: About the 'F' in RTFM)
Organization: Texas Instruments Inc
Date: Thu, 13 Aug 1992 17:57:11 GMT

In <1992Aug12.171748.26339@newshost.lanl.gov> jlg@cochiti.lanl.gov (Jim Giles) writes:

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

In the context of using them, my statement is correct.  The answer to
'how does this work' and 'what do I need to do to make this do this
thing' are the same question in a modular environment.

>Second, what it's supposed to do often doesn't match what it does.  

Then you REALLY have a problem.  If you have a sine routine and it
computes tangent instead, I'd say that more than the documentation is
broken.  I've found that a lot of the time when people come to me and
say "This doesn't do what the documentation says it does", the real
problem is that they've misread the documentation.

>Third, as badly as the documents are written, it's more cost effective 
>to have *one* person read them and have everyone else ask!  

No it isn't, and for a lot of reasons.  I'm sorry, but this assertion
is just plain silly.  That's like saying that it makes more sense on a
team of programmers to have one person know the language and all the
rest just ask him how to implement things.  Think about all the
impacts that would have, and then tell me again how it's more cost
effective to have one person read the docs and everyone else ask them. 

>You want 
>people to stop asking - write better manuals - they'll *voluntarily* 
>stop asking and read the new manuals instead.

This hasn't been my experience.  I used to get just as many questions
when I was doing VMS (which has a pretty good manual set) as I do now
with UNIX.  Face it; most people ask questions because it's easier
than looking it up for themselves.

>|> [...]
>|> >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).  

OH GOODNESS!  An *ADMISSION*!!!  Get a life, Jim.  If you want
'admissions', you might want to let ME make them if you're going to
claim they come from me.

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

Find another job, Jim.  One that lets you use something nice and
simple like MS-DOS.

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

Well, let me see if I can put something together to illustrate why
your claims here are just plain silly.  Suppose I had a spotlight that
had different colors and intensities of light that it could project.
Well, it does one thing and does it well.  It projects light.
However, spot size is adjustable, light intensity is adjustable, and
color is adjustable.  IF I DON'T CARE about those things, then I'm
unconcerned with either the options or what their defaults are.  If,
on the other hand, I *DO* care about those things, then it suddenly
becomes very important for me to worry about what the defaults on
those options are (and equally as important to know that there ARE
those options).

Sounds like you need to switch to the new RUM operating system.  That
stands for Read User's Mind.  Of course, it assumes that there is a
mind there to read.

>|> [...]
>|> 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), 

Geez, who ever promoted UNIX as being USER FRIENDLY?  

>the management signs off on it, 

Presumably they got some advice on this.  It just didn't happen to be
advice from you, so now you want to whine.  Fine.  Would you like a
little cheese with your whine?

>and there's nothing the technical staff can do about it.

Sorry, but this kind of attitude hardly sounds like 'technical staff'.
Sounds more to me like someone who had to learn something new and
didn't want to.

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

Yes, like their JOBS.  If they aren't qualified, they should seek
other employment.

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

Yeah, it's not real knowledge.  It just tells you how to do things.
Where, pray tell, do all the folks answering the questions get their
knowledge: immaculate reception?  As for 'human factors', why, how
Politically Incorrect of them!

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

Except, of course, that once they've read the manuals they know how to
look things up.  What happens if the person who HAS read them is out
sick, changes jobs, or gets hit by a bus?  What happens if the person
being asked all the questions decides that they need to get THEIR job
done?  How can anyone else get anything done if they have to ask what
to do at every step?  Sorry, but when everyone knows what they're
doing, productivity goes UP.  

>When people ask me questions, I answer them. <- Period.  

Then you do them a gross disservice, since you provide them with no
ability to find other things and no understanding of how they could
have found that answer.

>If they complain
>about the quality of the manuals, I agree with them (I found them nearly
>incomprehensible when I first read them too).  

If it was easy, they wouldn't pay us.  :-)

Seriously, nothing is perfect.  However, you don't do people any favor
by doing this.  All you do is convince them that the manuals are HARD.
So they will never look.

>I don't recommend that 
>*anyone* read the manuals except as a last resort (that is, when no one
>is available to *ask*).  

Sounds like the old 'knowledge is power' game to me.

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

Then you must have some real rocks around where you work.  We
generally require our engineers to know how to read before we turn
them loose on a computer.


-- 
"Insisting on perfect safety is for people who don't have the balls to live
 in the real world."   -- Mary Shafer, NASA Ames Dryden
------------------------------------------------------------------------------
Fred.McCall@dseg.ti.com - I don't speak for others and they don't speak for me.