Re: tlug: RTFM and advice

[Matt Gushee <matt@example.com>]

Scott Perlman writes:

 > Umm, if you're installing the package, you should have read the install notes.
 > 
 > All of them.

Okay, I'll take that on. Read all of them? Okay, let's say the
original author writes a BSD program called 'griffle'. He writes a
documentation file called README in which he explains what the program 
does and how to install it (but neglects to mention what platform he's 
talking about). Not a big problem because the program is in a BSD
archive anyway. But then some Linux developer hears about 'griffle,'
thinks it's really cool, and ports it to Linux. He includes a file
called README.linux, with new instructions. Then another guy patches
it for libspew, which adds a whole lot of new wrinkles. So to
get your attention he writes a file called README.1ST. Finally,
developer #4 sets the package up with GNU autoconf and writes new
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.

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.

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.

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.

Matt Gushee
Oshamanbe, Hokkaido
---------------------------------------------------------------
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