Re: tlug: RTFM and advice

[Scott Perlman <perlman@example.com>]

Matt Gushee did state upon Thu, Oct 22, 1998 at 04:44:20PM +0900:
> Scott Perlman writes:
> 
>  > Umm, if you're installing the package, you should have read the install notes.
>  > 
>  > All of them.
> 
> installation instructions called INSTALL. So now we have a package
> with four different documentation files written by different people,
> all containing contradictory instructions, and none of them giving any 
> clear indication as to the history of the package, or what has
> superseded what.

At that point I'd personally be VERY wary of the package.  Also check
the dates.  Seriously I've been there done that.  And in that case, the
uestion is asked "What am I doing?  I've tried to read this stuff and
it doesn't make sense?"  Then the answer isn't RTFM.  Of course if you
ask without mentioning that you've looked at the files, you'll probably
get told to look.

> Okay, you don't get that in well-maintained software packages like
> XEmacs or XFree86 or Apache. But I've seen cases very much like
> this. More than once. Quite a few times. And the poor user, who really 
> just wants to try out the application, is supposed to sift through
> this mess of documents and try to puzzle out how they all fit
> together.

If theres contradictions in the Docs, and it doesn't build with defaults
you've gotta ask or hack.  No issue.  Yes those docs are broken, a plea
to fix them with the help request is in order.  If you haven't read the
docs first, yo've no excuse.

> In theory, I agree with you. People should read the documents. But
> too often, the documentation is a damn mess. I'm not saying that
> developers need to be brilliant writers; but there are some who really 
> don't seem to think about what message the user is getting. If,
> just for a few moments, they were to take off their developer hats and 
> try to look at the READMEs, etc., from a user's point of view, we'd be
> in much better shape.

I can definitely agree with that sentiment.  Things can be better
commented.  (though I++; /*add one to I */ is overdoing it)  If the
docs are broken, they need to be fixed.

> Most of all, though, I think we need to be a little patient with
> people who have tried to read up and not been able to figure things
> out.

As long as they HAVE tried to read the docs.  When the question is,
what is XXX trying to say, I don't get it No problem.  Lets fix this
lack of understanding.  If you've read the docs and are confused, ask
get answers.  If you've not read the docs and are confused, well start
reading.

-Scott (who also still belive in minimal expectations of competency)
I don't buy very much in the way of electronic toys in Japan because
I am not competent to read the manual.  Which means that unless I have
a fair certainty I can figure it out on my own, or I have someone to
help, I don't go there.

-- 
"Then I was inspired,			| Scott Perlman
 Now I'm sad and tired,			| perlman@example.com
 After all I've tried for three years,  
 Seems like ninety." JC-JCS-ALW 
---------------------------------------------------------------
Next Nomikai: 20 November, 19:30 Tengu TokyoEkiMae 03-3275-3691
Next Meeting: 12 December, 12:30 Tokyo Station Yaesu central gate
---------------------------------------------------------------
Sponsor: PHT, makers of TurboLinux http://www.pht.co.jp