Just Follow The Rules!

If you’ve contributed notes to the PHP manual, you may have also had them modified, removed, or rejected by myself or another editor. If you disagree with it, that’s fine — we’re very open to hearing your side of things, and there’s been more than one occasion where I’ve agreed with the poster and replaced their note on the site.

There is, however, a proper way of doing that…. and the following thread excerpt shows the way not to do so. Keep in mind, the tenor of the thread was mostly professional from both sides, but nonetheless, the author’s name and email are protected from your prying eyes.

On Wed, Mar 4, 2009 at 08:31, <php-notes@lists.php.net> wrote:
> You are receiving this email because your note posted
> to the online PHP manual has been removed by one of the editors.
>
> Read the following paragraphs carefully, because they contain
> pointers to resources better suited for requesting support or
> reporting bugs, none of which are to be included in manual notes
> because there are mechanisms and groups in place to deal with
> those issues.
>
> The user contributed notes are not an appropriate place to
> ask questions, report bugs or suggest new features; please
> use the resources listed on <http://php.net/support>
> for those purposes. This was clearly stated in the page
> you used to submit your note, please carefully re-read
> those instructions before submitting future contributions.
>
> Bug submissions and feature requests should be entered at
> <http://bugs.php.net/>. For documentation errors use the
> bug system, and classify the bug as “Documentation problem”.
> Support and ways to find answers to your questions can be found
> at <http://php.net/support>.
>
> Your note has been removed from the online manual.
>
> —– Copy of your note below —–
>
> on the line:
>
> %R Same as “%H:%I” Example: 00:35 for 12:35 AM, 16:44 for 4:44 PM
>
> i think you mean
>
> %R Same as “%H:%M” ….

It’s true. I had rewritten the strftime() manual page last month at about 03:30 in the morning, and I’d made a mistake in transposing %M with %I. Those of you familiar with the date() function in PHP will recognize how this mistake probably came to pass (hint: in date(), ‘i’ is used to represent the minute).

So if you, dear reader, were the visitor to that page and noticed the error, the proper way of alerting us to the error would be to report a documentation bug so that we can repair it right away. It’s not as common-sense as you’d think, though, and it shouldn’t actually come as a surprise — some folks really don’t see it as a “bug” so much as something about which they, in good faith and with all good intentions, should warn other users.

Because it’s the improper venue for reporting bugs, though, and in following policy and procedure, I deleted the note. (I also immediately ate a slice of humble pie and committed the fix.)

…. but it didn’t end with that….

On Wed, Mar 4, 2009 at 11:51, frank <null@example.com> wrote:
> if a human actually reads this, you’ll see that i was in accordance
> with the rules about posting comments to this page. i am pointing out
> a typo ON THIS ACTUAL PAGE.

A human DOES read this, and one of them is replying to you right
now. Ooooh!!!!

I’m the one who not only deleted your note because it was
completely against the obviously-posted rules, but I’m actually the
one who did that particular manual entry. You’re correct that I had
mistakenly typed %I instead of %M, and I fixed that in the manual
source when I read your note (it will update on the web the next time
the system does its automatic update and build).

Now let me point something out to you — you were NOT in
accordance with the rules. It should’ve been posted as a bug, not as
a user note, and that’s mentioned multiple times on the site and
through the process of posting the note. It is then even printed in
the very email that you quoted herein in your reply. So you will see
why I deleted your note with prejudice.

Thanks for your contribution, and for pointing out my mistake.
Despite the incorrect manner in which the bug was reported, you’ve got
a keen eye and have helped to ensure that the manual is the best it
can be.

Perhaps a little strong, which would’ve garnered an apology from me under most circumstances. It wouldn’t have required one, but I would’ve offered it anyway. The majority of folks from the community who contribute to PHP are fantastic. Seriously, I genuinely mean that.

Our conversation took a different turn.

On Wed, Mar 4, 2009 at 15:04, frank <null@example.com> wrote:
> Hey man, no need to get your panties all knotted. The first email I
> received was obviously a form letter generated by your system…
> whether a human decided to send it out or not, I don’t know, and
> frankly don’t care.

Listen, Sally, if I want my underpants knotted, you can damn-well
bet that I’m going to wear them that way. And there isn’t a thing
that you or anyone else is going to do to stop me. In fact, as soon
as I’m done typing this message, I’m going to strip down right here in
my office and tie them up, just to prove that point.

There are probably some of you who know me well enough to actually wonder if I did, in fact, strip down right then and there. Well, I won’t go as far as to describe anything in vivid detail, but I will say that some breaking occurred, my chair was involved, and that’s about all I know at this point.

The point is, since some folks don’t notice the guidelines for contributing a user note when they’re doing it, and since a staggering number of the daily traffic of user notes, if you are going to retort with an attitude, don’t expect the rebuttal to be any less attitudinal!

(In all seriousness, my thanks to “frank,” though…. people like him who point out errors and flaws truly make things like the documentation better for everyone. I sure hadn’t noticed the error myself!)

Share

Leave a Reply

Your email address will not be published. Required fields are marked *

The CAPTCHA cannot be displayed. This may be a configuration or server problem. You may not be able to continue. Please visit our status page for more information or to contact us.