Re: Missing package documentation reminder

Helgi Þormar Þorbjörnsson wrote: > Actually it is enough, if you'd read the guidelines to PEAR then you'll > see that docs aren't required until you are releasing stable versions so > I'd say that either guidelines have changed while I wasn't watching or > that you haven't read them carefully enough :-) Hi Helgi, I respect the crunch of time, I imagine as a developer you receive far more emails than I do. If I were in your shoes, I would probably use a mail filter, as I've found this is more than effective in moving reminder messages into a folder where I can look at them later. Of course, this message comes once a month, and so it is also easy to just delete it, but I suspect it isn't the *volume* of mail that is bothering you, but just the *principle* of the thing, right? The guidelines have not changed, only stable packages are required to have documentation. However, the number of undocumented packages is too high (most of mine are undocumented, for instance). It gives PEAR a very bad reputation amongst the masses, as you undoubtedly have encountered. If we can fix this through other means, please let us know your ideas, but what PEAR has been doing for the past 7 years is not working, and will not work. Also, although Christian wrote the code, the idea for the reminder email was mine, feel free to yell at me instead of him :). By the way, if you don't actually have enough time right now to maintain the package, this is fully supported in the website, just mark yourself inactive and voila - all the reminder emails go away (right Christian? If not, we need to have a pow-wow). When the time returns, it is simple to reverse that and we of course welcome back prodigal developers as you know :). > Ohh I didn't know he got god rights to PEAR (= But all phun aside then > from what I can gather in your email then what ... 4 people said okey to > this whole email flood ? (if I include Arnaud and Greg) As with many proposals, there was 2-3 weeks of medium traffic on pear-dev about this process, including test displays of the functionality, and feedback from 10 or so developers (I'm estimating here). As far as I remember, the only negative feedback was on mistakes in the processing (packages marked as undocumented that actually were documented), so your complaint is the first. Understandable since you've been busy, of course. > Maybe I'm being too harsh on this whole thing but I think it the concept > needs a little tweaking before being as affective as it can be and still > follow the guidelines. > > Loath me if you like but I think this is pretty important what I was > trying to get across here above. Nobody loathes you :) and this is not a stand-off, we don't need to fight. You mentioned having the doc team take care of unmaintained/deprecated documentation. This is not a bad idea, but we need to clearly define the "doc team" in some way. Nobody will step forward otherwise. Christian: what if we took Helgi's suggestion and removed the doc emails for unmaintained/deprecated packages, and replaced it with a manual page listing the unmaintained/deprecated packages that need documentation? This way, doc folks could erase lines from the page as they fix stuff. As for stable vs. unstable packages, Helgi could we work out a compromise where you can accept the reminder email and we'll fix the unmaintained/deprecated issue? After all, it's not like the docs magically appear for stable releases, the docs need to be written prior to the first stable release, i.e. while the package is still unstable. Would this ease your pain Helgi? As I hope is clear, any good idea (yours included) must influence the process, and I think we can work out the differences you have quite easily in this case. Thanks, Greg