PEAR Forum :: PHP Extension and Application Repository

PEAR Forum Forum Index
 FAQFAQ   SearchSearch   MemberlistMemberlist   RegisterRegister   ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 
Documentation

 
Post new topic   Reply to topic    PEAR Forum Forum Index -> What do you miss in/about PEAR?
View previous topic :: View next topic  
Author Message
El Zagna



Joined: 14 Feb 2008
Posts: 9

PostPosted: Thu Mar 27, 2008 6:46 pm    Post subject: Documentation Reply with quote

One of the common complaints about PEAR is the lack of documentation on many of the packages.

I would like to propose that before a package can be considered "stable" that its documentation meet some minimum threshold of adequacy. In particular I would like to see a requirement that each package have a clear statement of its purpose. This could be something as simple as a sentence that starts with "The purpose of this package is to...".
Back to top
View user's profile Send private message
mark



Joined: 07 Jan 2007
Posts: 1235

PostPosted: Thu Mar 27, 2008 7:12 pm    Post subject: Re: Documentation Reply with quote

El Zagna wrote:
One of the common complaints about PEAR is the lack of documentation on many of the packages.

I would like to propose that before a package can be considered "stable" that its documentation meet some minimum threshold of adequacy.


That's already a requirement for all newer packages. Documentation and tests are required before a package can get the stable status. Only some older packages that were stable before this rule was set may violate this rule.

This forum is unofficial. If you want your suggestions read by more developers and especially by the PEAR Group, please send an email to the pear-dev mailing list, the address can be found on pear.php.net.
Back to top
View user's profile Send private message
El Zagna



Joined: 14 Feb 2008
Posts: 9

PostPosted: Thu Mar 27, 2008 8:06 pm    Post subject: Reply with quote

Well, of course a "minimum threshold of adequacy" is going to be a pretty subjective standard. Perhaps you can point me to the actual language for the required documentation.

Even so that doesn't address the statement of purpose issue. I realize that there is a "summary" and "description" required by each package, but all to often these get tripped up on the common problem of saying what the package does not why it exists.
Back to top
View user's profile Send private message
mark



Joined: 07 Jan 2007
Posts: 1235

PostPosted: Thu Mar 27, 2008 11:20 pm    Post subject: Reply with quote

Let's keep this discussion at one place. I saw that you've opened a bug report ...
(an email to pear-dev would have been better IMHO, BTW)
Back to top
View user's profile Send private message
El Zagna



Joined: 14 Feb 2008
Posts: 9

PostPosted: Fri Mar 28, 2008 12:32 am    Post subject: Reply with quote

Yeah, I realize that. The thing is I'm not sure who's looking at what, and which sites are actually active. If it's better to have the discussion elsewhere let's close this one down.

But really, this is pretty typical of the problems I've had with PEAR. The entire set up - the whole infrastructure if you will - strikes me as being hopelessly disorganized.

Right now I'm trying to decide on which technologies I need to focus on for my own marketability. Probably all of us are doing that to one degree or another. I thought that the basic concept behind PEAR was excellent, so I was willing to spend some time test driving it. Unfortunately the productivity bang for the buck has been pitiful.

It's a shame, really. I think that buried somewhere in that jungle of poor usability is some real gold, but man, oh, man, I don't think I've got the strength to get to it.
Back to top
View user's profile Send private message
Display posts from previous:   
Post new topic   Reply to topic    PEAR Forum Forum Index -> What do you miss in/about PEAR? All times are GMT + 2 Hours
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum



PEAR Forum topic RSS feed 
Powered by phpBB © 2001, 2005 phpBB Group

Provided by Ministry of Web developement