Re: [MacPerl] installing libraries in mac perl

[Matthew Langford <langfml [at] eng [dot] auburn [dot] edu>]

On Wed, 20 Oct 1999, Ronald J Kimball wrote:

> On Wed, Oct 20, 1999 at 09:18:01AM +0000, Bart Lateur wrote:
> > I don't see the need to distribute any totally irrelevant stuff. If
> > people want the original docs, there are places enough where they can
> > find them, e.g. in a distribution for a platform where it IS relevant.
> 
> I disagree.  All of the original docs should be distributed with MacPerl,
> just as they are distributed with every other Perl package.  If I don't
> want to read the docs for some other platform, it is simple enough to
> ignore them.

But they are _applicable_ to nearly every other environment!  They are
useless and confusing to a MacPerl newbie.

I don't have a problem with shoving the original docs into a legacy
folder, where they can be ignored. 

The way information is organized indicates its importance (or it can, with
great benefit).  Putting irrelevant information at the same level as very
highly important info is confusing to new users (the ones who most need
the info).  It will likely waste time, since a new user may not readily
distinguish where the to-be-ignored section begins and ends (and if things
aren't working, everything is put in doubt, right?).  If you go to the
trouble of color-coding sections for relevancy (this is a Mac, we can do
this), you will find yourself asking why include the junk section at all.

Under Unix, none of this matters.  If someone misunderstands or gets
confused, screw them.  They weren't worthy in the first place.  If you
can't stand the heat, get out of the kitchen.  They should hire an admin
who knows what's going on.  Or even better, we'll place _all_ the answers
to nearly every question ever asked by any Perl user, from the newbie to a
CPAN distribution-maker to a Perlguts hacker, in a hugely massive pool of
FAQs.  Then, if someone shows up in c.l.p.m and asks a question, we can
flame them for not finding the info in this vast FAQ.

Yes, I'm making a parody, but I think the truth is not far away.
Some cultures (ie, Unix culture, programmer culture)
chronically undervalue easing the new user experience.  The Mac culture is
not one of these.  MacPerl is a Mac program.  Therefore, it should also
not undervalue easing the new user experience.


> > What's the need for all this intimidation? Only absolute newbies will
> > ever attempt to read these docs. They don't even understand all that
> > they're reading, so it should be made as painless as possible. Stuff you
> > don't need to know AT ALL shouldn't be in there. Period.
> 
> Well, by all means let's take out all those modules that are included with
> Perl, because lots of people don't need those AT ALL.

C'mon.  This is nonsense.  No one will be desperately reading each module,
trying to figure out what's going on.  (In some sense, someone might try
to use this as a method to learn Perl, in which case the modules are all
highly relevant, unlike the docs.)  If you want to read the original docs,
put 'em out of the way, where someone with time on their hands can read
them.  While you're at it, why not throw in all the other platform
specific files for all the other platforms?  Should make good light
reading.  As long as they don't get in the way of more relevant
documentation, I don't care.

The key thing is not minimizing space usage (although somewhere in the
spectrum out to pound-cake recipes and favorite short stories this must be
considered).  It _is_ in presenting in easily digestible fashion (this
means one serving, in reasonable portions) the necessary information to
get started smoothly.  In practical experience, this will mean the minimum
necessary information, plus pointers to the rest to allow bootstrapping.



> > If you don't provide a newbie-friendly introduction README, then you'll
> > probably deter some people from even TRYING OUT MacPerl. They'll
> > download it, take one look at these docs, and throw everything in the
> > bin.
> 
> If someone can't handle a folder full of documentation, then they shouldn't
> be using MacPerl or any other Perl.  I expect that's condescending too.  So
> be it.

Congratulations, you have personified the Unix cultural approach to the
new user experience.  While this means you are probably eminently
qualified to handle programming questions, perlguts issues, and technical
problems, you would likely have problems producing a user-friendly
experience.  Why screw things up for people who do care about this aspect
of MacPerl?

Just because you walked twenty miles to and from school in the snow,
uphill both ways, doesn't mean everyone should, to toughen them up.
Improvements (in _organizing_ and streamlining the documentation) don't
endanger your status as an expert.



--
MattLangford 


# ===== Want to unsubscribe from this list?
# ===== Send mail with body "unsubscribe" to macperl-request@macperl.org