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.
Didou tries to propose some system, where notes will be categorized "to be integrated", so they can sooner become part of the manual. My practice when I was editing (a very little number of) notes, I left those needed integration, because I only had time to delete bad ones. If I would be able to mark them "to be integrated", I would have done it.
You are maybe right that this puts more work on the maintainers, and more need for education for those who would like to join the team, as they need to get familiar with the different categories. I myself still use "duplicate" in the bug reporting system sometimes to mark duplicate reports, because it seems so obvious, although I was told, that bogus is to be used for duplicate notes ;))
Rather than adding to the workload for each note, how about correcting the actions of the abuser themselves?
Erm, what do you mean?
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".
I think there are probably many notes, which deserve to be there. There are some notes actually submitted by manual authors, because they thought that it would not fit into the manual, but rather as a note. There are special things, like how to fix some bug affecting PHP in Apache 2.x, and the like. These are too specific to get into the manual, while they are important, and actual stuff.
Our users are mostly convinced that the user notes often contain valuable information (more often than crap). We get requests all the time to integrate them in the downloadable versions. I had created the special CHM version, and the feedback I received always pointed to the great inclusion of the user notes.... This may be an indication that the manual is weak at many places, yes. But it is also an indication IMHO that user notes have their own place.
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?
IMHO it would be nice to add some resons, the current letter sent out to submitters is way too general. But as I have said, I don't think that there is a need for so many reasons. Now we have one letter with all the reasons. If we split it into four, then the users will be more happy to get better information on why the note was deleted, and maybe don't do that submission next time.
Goba
-- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
