On Fri, Feb 24, 2012 at 16:54, Maciek Sokolewicz
<maciek.sokolew...@gmail.com> wrote:
> A few days ago I deleted a note, and the author sent a mail to the
> php-general list complaining about it. The answer by Dan was basically that
> the notes maintainers are overzealous and the author should contact the
> person who had deleted the note for clarification. Though I personally think
> saying that notes maintainers are overzealous is simply incorrect and may
> even be interpreted as insulting (yes, I do feel that way), that's not the
> point I'm trying to discuss.
Well, you're certainly welcome to feel insulted at any time, but
before you do, consider the facts: I'm a note maintainer as well, and
I'm also by far the most active. Thus, if anyone is overzealous at
times, it's likely to be me. It wasn't a slight against you (if I
intended it to be, I'd have CC'd you on the email personally to make
the point). I always encourage folks who complain about user note
removal to contact the editor who removed it so that they can best
explain their reason for deleting it. On occasion, I also confer with
editors (particularly the newer ones) to see their reasoning for
removing or rejecting notes. Most often, the reasons are justifiable;
very rarely (though it does sometimes occur), the editor needs a bit
of guidance as to what should or should not be removed.
The most basic guidelines I see to follow as a user note editor
are the very "dos and don'ts" the note submitter sees when adding a
note to the documentation. If there is an obvious violation or
ignorance of the rules, the note goes. Then, the guidelines (which
are not rules, and should never become rules, because it would detract
from the quality we've had thus far) come into play. From there, it's
essentially a subjective process, left to the individual editor as to
what adds value and what does not.
Over the years, I've had literally dozens of folks either question
or complain about my decision to remove a note, and I would say
roughly one-quarter of the time, through discussion, I'm convinced by
the submitter that the note does add value. Probably another
one-quarter of the time the discussion ends in the submission of
either a bug report or feature request. The remaining half is a
combination of cases where the user simply did not read the
pre-submission stanzas and either referred to another note or posted
"improvements" on an existing code snippet; posted an overtly biased
opinion on the language, site, or project members; linked to their own
website or blog; or the note just plainly didn't belong in the manual,
and I wasn't properly convinced otherwise by the submitter.
When dealing with the notes, the biggest thing to remember is that
we're editors; we're not here to please the submitting individuals,
but rather the readers of the manual and attached notes. That's going
to piss people off on both sides of the coin at times, and - quite
frankly - that's just too bad. As long as the documentation continues
to be as quality as it has been, my own opinion is that we're still
doing things just fine.
--
</Daniel P. Brown>
Network Infrastructure Manager
http://www.php.net/
