PHP PEAR Questions and Answers - Re: [PEAR-QA] Missing package documentation reminder

Author

Re: [PEAR-QA] Missing package documentation reminder

Helgi Þormar

2006-11-07, 6:57 pm

Is this a joke ? I mean really ?
Aren't we sending out enough global emails as it is ?

At least I remember when I made the whole "send out bug report reminders"
then I almost got teared a new one.

Will these emails be sent out monthly or ?

Btw. it's "stupid" to say a package is useless without docs because that's
simply false information :) even tho only the devs will see these
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 ... 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)

Even a better idea is to send these emails out only on maintained packages (
i.e. not marked as unmaintained or deprecated)

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.

- Helgi

On 11/7/06, pear-qa@lists.php.net <pear-qa@lists.php.net> wrote:
>
> Dear PEAR developer,
>
> Some of your packages in PEAR do not have end-user documentation
> in the official PEAR manual. Since the best package is useless
> without proper documentation, we ask you to write that for
> the packages not having any. And do remember that the auto-generated
> API-documentation does not replace end-user documentation as found
> in the manual. Use case and examples as well as an introduction
> to the way the package works is invaluable to the user wishing to use it.
>
> Your packages missing documentation:
> Cache, Tree
>
> If you have already written documentation located on an
> external server, plase consider transferring it into the PEAR manual.
> If that is not possible we ask you to create a link
> in the PEAR manual pointing to it.
>
> In case you are not a developer of one of the mentioned packages,
> the information in the package.xml file is wrong.
> Ask the lead of that package to correct the data.
>
>
> Regards,
> The PEAR QA team.
>

Gregory Beaver

2006-11-07, 6:57 pm

Helgi Þormar wrote:
> Is this a joke ? I mean really ?
> Aren't we sending out enough global emails as it is ?
>
> At least I remember when I made the whole "send out bug report reminders"
> then I almost got teared a new one.
>
> Will these emails be sent out monthly or ?
>
> Btw. it's "stupid" to say a package is useless without docs because that's
> simply false information :) even tho only the devs will see these
> 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 ... 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)
>
> Even a better idea is to send these emails out only on maintained
> packages (
> i.e. not marked as unmaintained or deprecated)
>
> 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.

Hi Helgi and all,

I think we need to rephrase to "a package is not considered up to the
quality standards of PEAR unless it has end-user documentation"
"Useless" is too inflammatory to have the desired effect.

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.

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 :)

Greg

Christian Weiske

2006-11-07, 6:57 pm

Greg, Helgi,

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.
[color=darkred]
Wording may be not optimal; please make suggestions.
[color=darkred]
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.
[color=darkred]
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.
[color=darkred]
Even if they are unmaintained or deprecated, they should have documentation.
[color=darkred]
Yes.
[color=darkred]
> 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

By the way, even today (in #pear) I asked again, and Arnaud agreed to
send the mails out.

[1]
http://xml.cweiske.de/pear-developer-docs.html
http://xml.cweiske.de/peardoc-coverage-extendet.html
http://xml.cweiske.de/peardoc-coverage-simple.html

--
Regards/MfG,
Christian Weiske

Gregory Beaver

2006-11-07, 6:57 pm

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 w

s 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

Sponsored Links