1) Who is allowed to manage users notes ?
I've been asked a lot of time by new commers to the PHP team : "can we help you managing the notes ?"
I've always answered that I wasn't the person to ask but that any help would be appreciated.
Maybe we can add this to the howto ?
IMHO, everyone (from the PHP team) should have the right to moderate the notes. No need to provide
access to other people. A team of 5 or 6 persons is moderating the whole stuff since two month, the
amount of notes in the database is decreasing every week. no need to external help.
It tends to vary over time. When people are very active, the notes are well maintained. Sometimes people become less active. From what I can see, I think the manual is still totally flooded with confusing, contradictory, and poorly written notes.
As far as "who is allowed to manage a given page of notes", I think the bare minimum should be
1. Those who know PHP, and the note subject, well.
2. Those who have experience with writing PHP's documentation (preferably). If notes editors are also writing documentation, *most* of the good notes can be deleted as they are integrated.
2) Reasons for suppression :
As approached in my first mail, we see from time to time abuses in the moderation,
Rather than adding to the workload for each note, how about correcting the actions of the abuser themselves?
Would that be a more effective solution than adding a greater workload to a simple system?
A smart note, which maybe deserve to be integrated to the manual lost, without any
understable reason :
"note xxxx was deleted from yyyy by [EMAIL PROTECTED]"
Why ? did "zzzz" read it all ? does he just want to show that he's "taking care" ?
There are a lot of valid reasons for deleting notes... ;-) If one cannot *trust* in someone else's competency to manage the notes, adding a bunch of categories that they "check off" will not fix that problem. Rather than "abusing" without a reason, they can simply "abuse" *with* a reason, valid or otherwise.
One more occasion to fit our readers needs is lost here.
some notes disserve to be on the users notes, without being deleted nor integrated.
Can you provide some examples? I perceive the optimal manual as a manual without *any* notes. If the manual is good enough, no additional notes and explanations would ever be needed. So, if a page *has* notes, that is a sign that more effort should be applied to improving the documentation... to a point where PHP no longer requires "external help".
A new note is posted :
- if the note should be deleted (deleted, not rejected as described by the current howto) we do
and we provide a reason.
here's IMHO what we'll need :
bad_mail: the note should be rejected, but the provided mail is buggy, no need to give more
work to the server.
trash : foreign language, spam, whatever that make it clear for every moderator that the note
should be deleted
wrong : the user is posting a poorly written code, is saying something wrong, is answering to
someone else
old : tricks on how to compile an old version of PHP with an old library deprected from the ages of snow.
who cares ? it's confusing for people trying to solve problems with new versions.
- if the note should be rejected :
reasons :
bug : the user is reporting a bug ? we send him a mail linking to http://bugs.php.net
support : the user is asking for help ? we send him a mail linking to http://www.php.net/support
(remember that if the mail address is buggy, you should *delete* the note with the reason : bad_mail)
This is missing a large number of "other" reasons for deleting/rejecting notes, here are some reasons from poking around notes tonight:
1. Note cross-page duplication: such as a 20 line ldap example that someone chose to put on the ldap_open, ldap_bind, ldap_add, and ldap_close pages.
2. Note use/example duplication, where a page has 5, or 15, examples that all accomplish the same thing, with slightly different syntax or variable names. (This tends to create less clarity about function use, not more). If the manual's examples are not clear enough, this will tend to happen.
3. Cross links/deep links to other sites that are easily found: I don't think it's useful to make the notes pages into a PHP search engine, where multiple notes are simply links to other sites. (Example: putting multiple links to all kinds of "regular expressions tutorial sites" on the regexp pages, or faqts using hundreds of pages in the php manual... we can link to them from one page).
4. Duplicate requests for doc fixes: If the docs are bad, only one note is needed to ask for corrections to the docs. Having 15 notes will not get it fixed any faster.
5. Old notes that do not relate to old PHP versions, but things like archaic web browser versions ("To fix a problem with IE5...").
6. Notes about problems that are *so* unrelated to the page as to be meaningless (Example: A note on a file upload page about a buggy ethernet card/driver causing upload problems.)
7. Didn't RTFM: Notes which say (or imply) that the user didn't actually read the page (such as notes to set important configuration directives... which are mentioned on the page).
8. Slashdot-style Opinion notes: For example, people posting how they *think* a function should work, how OO "should" work in PHP, etc.
9. Pointless nit-picking notes: For example, 3-15 notes arguing over "whether or not /r/n is RFC822 compliant".
10. Repeat notes: For example, quoting an entire note and then noting that it helped someone.
11. Reworded-bug-report notes: A clever way of getting around some past or present PHP bug is *still* a bug report. The solution is fixing PHP.
12. Coding-101-notes: Notes that mention that things like "closing quotes" matter. (Uhm...)
(etc.)
I'm sure we could create labels for all of these (or apply existing ones), but to what end? If the end product is a good manual, annotated and then improved as needed, how will it help reach that goal if each note submission/rejection/deletion/integration requires more work? Especially since the manual is still filled with notes that need to be integrated, or removed?
Ronald Chmara
Ronin Professional Consulting LLC
678-530-9542
"The question of whether a computer can think is no more interesting than the question of whether a submarine can swim." ---Dijkstra
-- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
