Some comments on the PEAR site

[Bill Norton]

Uhm... I'm not sure how to say this delicately, but your site is a big
stinkin' mess. Sorry to be so rude, but then you should have seen my first
two drafts.

I realize that this is all open source stuff and nobody is actually being
paid to make sure that the site is actually useful to anyone trying to use
PEAR, but still...

I have spent a ridiculous amount of time getting PEAR installed and
configured, and I can only hope that there will be some payoff in the end,
but I can't tell yet because I've had so little time to actually test drive
any of the packages.

Let me be clear that the issues I'm expressing here have nothing to do with
PEAR per se, they have to do with the layout of the site and the
impenetrable quality of the documentation. So let me get down to some
specifics.

We can start with the color scheme. Using dark green for the links was, I
suppose, inspired by the idea that real pears are sometimes green. The
problem is that there is not enough contrast between the link colors and the
text so it's hard to determine where the links are. I suppose it could have
been worse. You could have gone with yellow since that's the color of most
pears. It would help if you simply bolded the links or gave them another
font, or didn't style them at all.

Then there are the more substantive issues. Let me ask you this - do you
know who your audience is? It's a pretty safe bet that the vast majority of
users that come to your site want to know one of two things: (1)What is
PEAR? and (2) How do I install it? Well, on the home page you say what PEAR
is: "PEAR is a framework and distribution system for reusable PHP
components." Not that that really tells you anything, but at least it may
give the reader an idea of sorts.

OK, so how do you install it? Well, there's no clue on the home page. No
"Download" or "Install" link. So you have to start clicking around.
"Support" maybe? No, not there. "Documentation" perhaps? Nothing obvious
there. But wait! There's an "About PEAR" sub-menu under "Documentation". Now
usually an "About" link takes you to some page that talks about the company
and its people, but this one is apparently the table of contents for the
first section of the manual (English version) and there under item 2 is
"Installation". Great! So you click on "Installation" and the first thing
you see is, " This chapter requires that you are already familiar with the
general structure of PEAR." Holy #$%^&*!!! You've got to be on some serious
medication to not be getting a little frustrated by now.

Well, let's move on. Still trying to install the darn thing I see that "If
you have a recent installation of PHP, you can relax: The PEAR base
installation is already there, unless you have compiled your PHP with the
../configure flag --without-pear." Well, I have PHP 5.2, and I don't recall
setting any flags, so I guess my base installation is already there. OK, so
where is it? The only PEAR related things I see are go-pear.bat and
go-pear.phar. Is THAT the "base installation"? Well, no. Those are the
things you need to run to actually install the base product. I've read that
paragraph several times and I'm still not sure if it's factually wrong or
just hopelessly obtuse.

And that's just the first two paragraphs of the Installation/Introduction
section. The third paragraph talks about installing additional packages with
the package manager. So, is the package manager a separate installation from
PEAR itself? Who knows. But we can all relax in the knowledge that it works
just like Debian's "apt-get" package management utility and "yum". Say WHAT?
What the hell is apt-get or yum, and why do I need to know this?

Well, that's enough for now - probably too much. I apologize if the tone of
this was a bit snitty. It's just that get tired of seeing the actual needs
of the end user so often left as an afterthought.

[Daniel O'Connor]

Hey, thanks for the email Bill!

but your site is a big stinkin' mess.

I believe some work is going towards vastly improving the layout and
design of pearweb at the moment, but it is a big task, as you rightly
point out.

If you're still keen, feel free to lodge some bugs around specific
usability issues:
http://pear.php.net/package/pearweb

Nothing helps more than some screenshots, and if you're keener,
mockups of solutions.

For instance:
http://flickr.com/photos/clockwerx/510829118/ (before)
http://flickr.com/photos/clockwerx/510829112/ (after)

I have spent a ridiculous amount of time getting PEAR installed and
configured, and I can only hope that there will be some payoff in the end,
but I can't tell yet because I've had so little time to actually test drive
any of the packages.

I think most pear developers would say there's some value! :)

We can start with the color scheme. Using dark green for the links was, I
suppose, inspired by the idea that real pears are sometimes green. The
problem is that there is not enough contrast between the link colors and the
text so it's hard to determine where the links are. I suppose it could have
been worse. You could have gone with yellow since that's the color of most
pears. It would help if you simply bolded the links or gave them another
font, or didn't style them at all.

Got a screenshot?
I'd wager for most of us the links seem pretty clear and visible - or
at least they do for me.
It'd be helpful to see what you're seeing

Installation sucks

Absolutely, this is an area which could do with some UI love.

Are there any examples which really stand out to you on the web as
"this is easy, and workable, and does what I need"

[Daniel O'Connor]

Hey Bill,
Does
http://www.flickr.com/photos/clockwerx/2340532410/
... go in the direction you wanted/expected?

[Daniel O'Connor]

I've lodged http://pear.php.net/bugs/bug.php?id=13449 and
http://pear.php.net/bugs/bug.php?id=13448 so far.

Now, this is no promise these things will be fixed, but at least they
certainly won't be forgotten.

Also, it's probably best to do a reply-to which includes
pear-***@lists.php.net - that way it reaches a much bigger
audience than lil ol' me.

Hi Daniel -
Thank you for your measured and diplomatic response to my rant. Let me
comment on some of the specific items you ask about.
Color Scheme: Let me make it clear that the problem that I have with the way
the links are styled is not that you can't see them, but rather that they
are almost indistinguishable from the text. The text is black and the links
are dark green (#006600). While that may be OK for many, for my 60-year old
eyes, there's just not enough contrast to make the links pop out, especially
when the link is separated from the text. For example, take a look at
http://pear.php.net/package/pearweb and notice how "PHP License" is separate
from any other content. It's very hard for me to tell that that's a link
based on any visual clues. You need something else to make it obvious to the
user where the links are. This could be done simply by using the default
text-decoration styling which would underline all links.
A more readable example: Take a look at Harry Fuecks article over at
Sitepoint, "Getting Started with PEAR - PHP's Low Hanging Fruit"
(http://www.sitepoint.com/article/getting-started-with-pear). While that
style might be a bit chatty and informal for the PEAR site, it is much
clearer about what PEAR is, why you might want to use it, and how to go
about installing it.
Keep in mind who your audience is. I'd wager that the vast majority of your
visitors come to your site because they've heard about this PEAR thing and
want to know if and how it will be of any benefit to them. You've got maybe
two minutes to sell them on the "product" before they wander off somewhere
else. Actually two minutes may be generous. There are actual metrics on this
sort of thing, but I can't remember where I saw them.
I'd also wager that almost no one comes to the site to see what the latest
changes are (the "Hot off the Press" section for the PEAR site). I realize
that this probably doesn't sit well with the developers who have been
working their asses off to make those changes, but in reality most users
really don't care. So don't put something on the first page that most users
don't care about.
Once the user is convinced that PEAR is of some value to them , the next
thing they will want to do is install it. That's why you need a big,
stinkin' "Install PEAR" button on the home page. The new approach you are
suggesting on Flicker (http://www.flickr.com/photos/clockwerx/2340532410/)
strikes me as a great improvement.
OK, that's all for now. I'd actually like to hear other's comments on all of
this.
Bill Norton