Prev: User activation
Next: pear install CAS-1.0.0.tgz
From: Gary on 13 Aug 2008 12:37
Is there any other end-user documentation, besides the two Ken Guest
recently mentioned (the online manual and the SitePoint article by Harry
Fuecks at http://www.sitepoint.com/article/getting-started-with-pear)?

The online manual is haphazard and incomplete (not to mention being
unreasonably difficult for beginners to find it). The SitePoint article
does a better job at describing the installation of Pear, but only
briefly gets into actual use.

I'm looking for something that would cover a variety of user scenarios,
as well as getting into non-obvious command subtleties. The scenarios I
have in mind include things like coping with multiple channels (e.g.
finding a package you've already installed when you don't remember the
channel), installing multiple versions side-by-side, downgrading
installations, understanding and diagnosing common error messages, etc.
As for command subtleties, I keep getting frustrated because list-all
doesn't, I can't find how to list descriptions of local packages without
using list-all, and so on. In particular, it would be really useful to
distinguish the commands that apply to end users from those that apply
to package developers.

Thanks,

Gary
From: "Christian Weiske" on 13 Aug 2008 13:48
> Is there any other end-user documentation, besides the two Ken Guest
> recently mentioned (the online manual and the SitePoint article by Harry
> Fuecks at http://www.sitepoint.com/article/getting-started-with-pear)?
I'm not aware of any.

> The online manual is haphazard and incomplete (not to mention being
> unreasonably difficult for beginners to find it).
Believe me, we are deeply interested in making that documentation better.
I rewrote the whole cli usage guide some months ago and think it's quite
better than before - but there are always things make better.


> I'm looking for something that would cover a variety of user scenarios,
> as well as getting into non-obvious command subtleties. The scenarios I
> have in mind include things like coping with multiple channels (e.g.
> finding a package you've already installed when you don't remember the
> channel), installing multiple versions side-by-side, downgrading
> installations, understanding and diagnosing common error messages, etc.
> As for command subtleties, I keep getting frustrated because list-all
> doesn't, I can't find how to list descriptions of local packages without
> using list-all, and so on. In particular, it would be really useful to
> distinguish the commands that apply to end users from those that apply
> to package developers.

That's a good list to start with. You know, only if we get questions we
can sit down and write manual pages that explain them. The pear-dev
mailing list and the irc channel are relatively quite now, so we don't get
that much input.


Regards,
Christian

From: Gary on 14 Aug 2008 12:53
Christian Weiske wrote:
> ...
> That's a good list to start with. You know, only if we get questions we
> can sit down and write manual pages that explain them. The pear-dev
> mailing list and the irc channel are relatively quite now, so we don't get
> that much input.
>
Thanks for your reply, Christian. I can't speak for others, but I find
that I'm far more likely to participate in forums and wikis than to
mailing lists or IRC. And I hesitated to raise the issue because,
frankly, my initial reaction was that the manual needs a major
refactoring into two separate manuals. There are three classes of PEAR
users: end-users who just want to install and maintain PEAR packages,
contributors who want to construct and contribute them, and PEAR
maintainers, who want to work on the actual PEAR code and not just
contributed packages. It may make sense to serve the last two user
groups with a single manual, but the people who just want to use PEAR
packages need a manual that doesn't begin with coding standards.

Or to put it another way, there need to be communication paths that feel
appropriate for such users and issues. The general list is so full of
package announcements that I was reluctant to sign up at first. (I hope
I'm not fanning the flames of an old debate about whether announcements
should get forwarded to the general list.)

Regards,
Gary
 | 
Pages: 1
Prev: User activation
Next: pear install CAS-1.0.0.tgz