Re: Missing package documentation reminder

On Tue, 07 Nov 2006 20:00:49 +0100, Christian Weiske wrote: > Greg, Helgi, > > >>> Aren't we sending out enough global emails as it is ? > I did announce this step five days ago, awaiting answers if that is ok > or if there are any objections. The two replies I got were positive. > >>> Btw. it's "stupid" to say a package is useless without docs because >>> that's >>> simply false information :) > Wording may be not optimal; please make suggestions. > >>> emails, especially when the package is marked as beta, if those emails are >>> going to be sent out then please do so only on stable package where I'm >>> actually listed ... > Many, many packages in PEAR are stable only but widely used, and do not > have any end user docs. So sending it only for stable packages is not > enough. 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 :-) I for one don't want to get nagged about none stable packages when I don't have to have docs on them (don't take it the wrong way but having a tool that goes against the bible, i.e. the guidelines is kinda odd and bad IMHO) >>> Use the database, not an outdated package.xml file (it even seems a >>> bit of wasted cycles to use the package xml because we have a DB for >>> this stuff) > 1) If the package.xml is outdated, it needs to be fixed. 2) While it is > easy for the QA_Peardoc_Coverage package to scan package.xml files since > it needs to check the .php files of the packages anyway (see [1]), I > don't have any information if it's possible to access the database from > outside or how the structure is. Take a driver approach to the package ? Shouldn't be too hard to support the current way (so people not with access can actually use the package) and yet have a pearweb driver to get the full performance and easy of use. Maybe Greg can write the driver or someone else in QA but the struct is easy to get from CVS as anything else on pearweb ;) I also know that out of date package xml file is not good (tm) but that's more often the case then not. >>> Even a better idea is to send these emails out only on maintained >>> packages (i.e. not marked as unmaintained or deprecated) > Even if they are unmaintained or deprecated, they should have > documentation. That's a none sense, so if I have a package I don't intend to maintain or I created a new package that actually has docs then I still have to make at least one page per package ? Please, it's not like every PEAR dev doesn't have enough on their mind, that's something a doc team could do for an instance if it's so crucial to have a one liner docs. >>> Just my 2 cents, might have missed siome discussion about this since I >>> only look at the lists ever so often but so it goes, I got rather >>> curde internet access at work so I can't really look it up. > Yes. > >> I think all deprecated packages need a 1-page manual entry that links >> to the docs for the new package, just as packages like phpdocumentor >> need a 1-page entry linking to external docs. Perhaps the reminder >> email could suggest this as well. > +1 > >> As for the email being useless, I think the fact that there was a reply >> on pear-dev from a developer I've never heard of before asking how to >> write docs completely refutes your argument :) > +1 Right ...... > By the way, even today (in #pear) I asked again, and Arnaud agreed to > send the mails out. 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) 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. - Helgi