Re: [PHP-DOC] Notes system (again)
Jared W wrote: [ ... ] Some good points here :) I'm leaning towards weaning the entire PHP documentation process away from the general php bugs system, as the two just don't seem to be the best of friends. This new notes system can be a big part of the new setup. Regards, Philip Have to agree 100% with you Philip the documentation bugs should have its own system, integration with the notes system could work, mark the note as a bug and its sent over to the bug system? Solves 2 problems at once really to be honest I don't like touching the bugs system it seems to be snipers's baby and likely to hurt me if I touch it ;) I think that we need to distinguish between two things : - a documentation bug : IMHO, this one should be handled by bugs.php.net. We could click on a link that automatically will post the bug report with the notes lists email address. - a note that can be added to the documentation (an example to add, a warning that will avoid confusion, etc.) : since there is no bug here, we shouldn't create one. IMHO, this is when the new interface is needed. The note would be marked as to be integrated. The note will then hide from the online documentation and show in the browsable interface. With this interface, someone with good knowledge about the topic and enough karma to phpdoc should be able to browse this kind of notes, commit some changes and then delete the entry (or mark it as integrated so we can have some statistics) In regards to the current notes system from a users point of view it's the best resource out there, people are constantly commenting in irc how much they are being helped with it, the comments are getting better as people seem to know what is accepted and not these days, although some more monitoring could be done better some how as a lot of shitty notes still get through, bugs etc etc just have a look at some obscure functions some time Having never seen the email that is sent to rejected letters I cant comment however there has been a lot of noise on it as of late so I assume its not up to par, so maybe a complete overhaul is in order? http://cvs.php.net/co.php/php-master-web/manage/user-notes.php?login=2r=1.34 see the contents of $reject_text didou
Re: [PHP-DOC] Notes system (again)
Gabor Hojtsy wrote: That was my original idea. Anyone can submit a bug report, fixing it should be left to whoever has CVS access to phpdoc. We can even use for the bug report originator the php-notes lists address, that way the other editors will know that someone did mark a particular entry as such and does not duplicate the effort. Some good points here :) I'm leaning towards weaning the entire PHP documentation process away from the general php bugs system, as the two just don't seem to be the best of friends. This new notes system can be a big part of the new setup. Have to agree 100% with you Philip the documentation bugs should have its own system, integration with the notes system could work, mark the note as a bug and its sent over to the bug system? Solves 2 problems at once really to be honest I don't like touching the bugs system it seems to be snipers's baby and likely to hurt me if I touch it ;) Am I correct if I think that you are suggesting that the doc group should have a bug system on its own? Like PEAR and PECL? Are the PEAR and PECL bug systems a copy of the original bug system? Is it a good idea to have four differently evolving copies of the same bug system? I think the problem here will be for core developpers. Right now, if some user post a bug report about the zend engine (or some part of the core) but the developper think that this a documentation bug, he will just want to change the category to Documentation bug and won't struggle to post a new bug on the new documentation bugs interface and then mark the original post as bogus or won't fix. But again, wa can do some kind of magic here. Having a separate system for the documentation bug will help to categorize those bugs. We can for example create a category for each extension, etc. didou
RE: [PHP-DOC] Notes system (again)
Well, if someone has no CVS account then he will not be able to fix the docbug in the documentation CVS, so he can only mark it 'to be fixed in the toc' AKA 'docbugreport', so someone with a CVS account can fix it. If the note maintainer system would enable someone to move a manual user note to be a bug, then this would not require a CVS account. Some authentication will be needed throughout the process (which requires a CVS account now), but the bug can be opened with the email address of the original user note submitter That was my original idea. Anyone can submit a bug report, fixing it should be left to whoever has CVS access to phpdoc. We can even use for the bug report originator the php-notes lists address, that way the other editors will know that someone did mark a particular entry as such and does not duplicate the effort. Some good points here :) I'm leaning towards weaning the entire PHP documentation process away from the general php bugs system, as the two just don't seem to be the best of friends. This new notes system can be a big part of the new setup. Regards, Philip Have to agree 100% with you Philip the documentation bugs should have its own system, integration with the notes system could work, mark the note as a bug and its sent over to the bug system? Solves 2 problems at once really to be honest I don't like touching the bugs system it seems to be snipers's baby and likely to hurt me if I touch it ;) In regards to the current notes system from a users point of view it's the best resource out there, people are constantly commenting in irc how much they are being helped with it, the comments are getting better as people seem to know what is accepted and not these days, although some more monitoring could be done better some how as a lot of shitty notes still get through, bugs etc etc just have a look at some obscure functions some time Having never seen the email that is sent to rejected letters I cant comment however there has been a lot of noise on it as of late so I assume its not up to par, so maybe a complete overhaul is in order? Yet again having our own bug page will help enormously in moderating the notes page 1) a lot more options rather than deleting a bug request because it doesn't belong there and it never being dealt with, im sure it happens mark it as a bug and bang it has everyone's attention I guess im rambling again I do that just my 2c's Thanks jared
Re: [PHP-DOC] Notes system (again)
That was my original idea. Anyone can submit a bug report, fixing it should be left to whoever has CVS access to phpdoc. We can even use for the bug report originator the php-notes lists address, that way the other editors will know that someone did mark a particular entry as such and does not duplicate the effort. Some good points here :) I'm leaning towards weaning the entire PHP documentation process away from the general php bugs system, as the two just don't seem to be the best of friends. This new notes system can be a big part of the new setup. Have to agree 100% with you Philip the documentation bugs should have its own system, integration with the notes system could work, mark the note as a bug and its sent over to the bug system? Solves 2 problems at once really to be honest I don't like touching the bugs system it seems to be snipers's baby and likely to hurt me if I touch it ;) Am I correct if I think that you are suggesting that the doc group should have a bug system on its own? Like PEAR and PECL? Are the PEAR and PECL bug systems a copy of the original bug system? Is it a good idea to have four differently evolving copies of the same bug system? Goba
Re: [PHP-DOC] Notes system (again)
The integration bit could be done as a documentation bug report, with the advantage that there will be a track record of the action/contents. Do you mean that user notes would be automatically turned into documentation bug reports if decided by a note admin? This sounds good to me :) Others will surely point out the downsides :) One huge downside is the bugs system didn't have such a task in mind when it was created, and a seperate system would be more useful and well used. Since we're talking about actually implementing the note maintainer system[1], I think said system should handle this and not bugs.php.net All the ideas in this thread[2] and other[3] threads seem to make this the desirable option. And this was discussed at the 2003 phpdoc meeting[4] and some interesting findings[5] came about. Because people agreed that non-CVS users should be able to maintain notes, this is yet another reason why bugs.php.net shouldn't get involved. Well, if someone has no CVS account then he will not be able to fix the docbug in the documentation CVS, so he can only mark it 'to be fixed in the toc' AKA 'docbugreport', so someone with a CVS account can fix it. If the note maintainer system would enable someone to move a manual user note to be a bug, then this would not require a CVS account. Some authentication will be needed throughout the process (which requires a CVS account now), but the bug can be opened with the email address of the original user note submitter Or I was unable to interpret your thoughts properly? :) Goba
Re: [PHP-DOC] Notes system (again)
--- Gabor Hojtsy [EMAIL PROTECTED] wrote: The integration bit could be done as a documentation bug report, with the advantage that there will be a track record of the action/contents. Do you mean that user notes would be automatically turned into documentation bug reports if decided by a note admin? This sounds good to me :) Others will surely point out the downsides :) One huge downside is the bugs system didn't have such a task in mind when it was created, and a seperate system would be more useful and well used. Since we're talking about actually implementing the note maintainer system[1], I think said system should handle this and not bugs.php.net All the ideas in this thread[2] and other[3] threads seem to make this the desirable option. And this was discussed at the 2003 phpdoc meeting[4] and some interesting findings[5] came about. Because people agreed that non-CVS users should be able to maintain notes, this is yet another reason why bugs.php.net shouldn't get involved. Well, if someone has no CVS account then he will not be able to fix the docbug in the documentation CVS, so he can only mark it 'to be fixed in the toc' AKA 'docbugreport', so someone with a CVS account can fix it. If the note maintainer system would enable someone to move a manual user note to be a bug, then this would not require a CVS account. Some authentication will be needed throughout the process (which requires a CVS account now), but the bug can be opened with the email address of the original user note submitter That was my original idea. Anyone can submit a bug report, fixing it should be left to whoever has CVS access to phpdoc. We can even use for the bug report originator the php-notes lists address, that way the other editors will know that someone did mark a particular entry as such and does not duplicate the effort. Or I was unable to interpret your thoughts properly? :) Goba = --- Jesus M. Castagnetto [EMAIL PROTECTED] __ Do you Yahoo!? Protect your identity with Yahoo! Mail AddressGuard http://antispam.yahoo.com/whatsnewfree
Re: [PHP-DOC] Notes system (again)
Well, if someone has no CVS account then he will not be able to fix the docbug in the documentation CVS, so he can only mark it 'to be fixed in the toc' AKA 'docbugreport', so someone with a CVS account can fix it. If the note maintainer system would enable someone to move a manual user note to be a bug, then this would not require a CVS account. Some authentication will be needed throughout the process (which requires a CVS account now), but the bug can be opened with the email address of the original user note submitter That was my original idea. Anyone can submit a bug report, fixing it should be left to whoever has CVS access to phpdoc. We can even use for the bug report originator the php-notes lists address, that way the other editors will know that someone did mark a particular entry as such and does not duplicate the effort. Some good points here :) I'm leaning towards weaning the entire PHP documentation process away from the general php bugs system, as the two just don't seem to be the best of friends. This new notes system can be a big part of the new setup. Regards, Philip
Re: [PHP-DOC] Notes system (again)
On Tuesday 18 November 2003 00:35, Jesus M. Castagnetto wrote: --- Mehdi Achour [EMAIL PROTECTED] wrote: Hi ! It's been a while since the thread [1] wasn't discussed, so here we go again. After 3 months, here's the situation reviewed : 1) - Notes posted : We receive about 30 notes a day, most of them are I - Asking for help II - Pointing to a bug in the documentation (typo, something missing, etc..) III - Noise IV - Scripts to help other users Perhaps II could be handled if there were an option for the notes editors to submit the user note bug, Thats something I like. I've seen bug reports in the notes, that don't have an email address so I can't reject them.. I don't always have the time to directly fix it and it gets lots in the rest of the notes... I just say this note: Note that the config variable sybase.compatability_mode must be misspelled. In English, the word is spelled compatibility, so don't use your English knowledge. I think that this will be submitted as a doc bug. I took the time to check the source and there is nothing wrong. maybe the 'to be submitted as bug' should be re-checked to ensure that there are no bogus bug reports (I'm sure the doc and bug teams will be happy with that) the same way it is deleted/rejected/edited nowadays. I and III should be removed, and IV should be dealt on a case by case basis, some examples might be useful enough to make it into the manual entry's body. 2) - Problems with the actual system : I - The rejection mail is too generic and deals with all the situations that may have caused the rejection. If the poster didn't read all the warnings while submitting the note (don't post support questions, don't, don't), will he really read such a mail ? Yep, it is a quick hack. The idea was that perhaps if the person did not read the first 2 times the info was shown, it might read the third time. It did decrease the number of junk when we started using that system, but I agree that maybe something more sophisticated is needed. II - We see some good notes deleted, and nothing done. We have lost one more occasion to provide a better manual. Agree. As you mentioned in IRC, I am all for having a way of labelling those entries to be added to the manual. I can only agree here.. But when there is a 'to be added to the manual' thing it will atleast help me finding the notes and manual files that I wanted to edit/add, but forgot about it after because I didn't have the time at that moment III - When a note is deleted, we doesn't know why it was (from time to time I think that the one who deleted it don't know the reason..) Adding a reason files is very handy to actually take a look at what your doing.. but it will take some more time.. That is true. Back when I had more time to help w/ the notes admin, there were cases were notes that were important were removed by a novice editor. IV - We sometime rejected notes with bad-formed emails, it only gives the mail server more work (and we know how the mail server suffers from time to time) Along w/ the rejection code, I had put some code to test the validity of the email, not just using regexes but also talking to the MX server to check that there was a real mailbox w/ that username, but that caused performance degradation in some cases. 3) - Solutions : First shot, solving I, II and III. Same as proposed in [1], but a little reviewed (three months has passed by) Possible actions : Rejected Deleted To be integrated Integrated No action (another maintainer will maybe take one of the four actions mentioned before) I would add: Send bug report what about the option on that page: Send General bug report (it has something to do with the function) Send Documentation bug report (somthing with the docs) I don't think we need all the sections that exist on bugs.php.net, do we? Possible reasons : * Rejected : - bug : Didn't you read all the warnings before posting ? Please fill in a bug report. we can also mention features request here. - support : have a look at php.net/support.php - not our thing : Hey !! why is www.somesite.com pointing me here ???. Answer drop a mail to the webmaster of this site * Deleted : - trash : a note that doesn't belong in our manual at all (spam, irrelevant, wrong note, bad coded script, submitted twice, etc..). Everything that is not part of the other reasons for deleting a note. - integrated : the note is now in the official manual. We can also make the script send an automatic mail to the submitter (he will certainly be pleased) * to be integrated : - this note is really relevant and should be in our manual ? mark it as integrated. If you
Re: [PHP-DOC] Notes system (again)
The integration bit could be done as a documentation bug report, with the advantage that there will be a track record of the action/contents. Do you mean that user notes would be automatically turned into documentation bug reports if decided by a note admin? This sounds good to me :) Others will surely point out the downsides :) Did someone modify the way the email is validated. Last time I saw it, it was using a regex. Might want to check if the regex has been changed or the validation omited altogether in the source code. The email validation code have not evolved much since you have added, even the testing code is in CVS you have added :) Since it is just regex, obvious errror are not cought in the email address, which indicate for a human being that it it probably not a real email address... One thing I always wanted (and wrote code that was never integrated for some reason), was to let notes editors register which manual sections/pages they would be interested in editing, that way he/she would only recieve the emails related to those sections (of course all the other notes will still go to the Notes mailing list). Last time this came up, it was said that there is not much note admin currently to handle the notes, and the notes could be handled 'efficiently enough' if the changes proposed by Mehdi would be implemented. At least this is what I can remmeber. Since I am not an active note maintainer, don't take this opinions seriously. Goba
Re: [PHP-DOC] Notes system (again)
Gabor Hojtsy wrote: Submitter email The note Manual page Delete : trash Integrated Reject : bug support not our thing To be integrated Search the note database Seems to be fine with me. The URLs need to be shorter and more clear IMHO. It would be nice to set up a 404 handler on master.php.net, so we would be able to do tricks there for these kind of URLs. I don't think that it would be a good idea to abuse the PHP.net shortcut namespace for these shortcuts. +1 on this. IMHO, the 404 should not only handle the notes part but also stuff like users, mirrors, etc. But this is out of topic for the moment :) didou
Re: [PHP-DOC] Notes system (again)
Jesus M. Castagnetto wrote: --- Mehdi Achour [EMAIL PROTECTED] wrote: Hi ! It's been a while since the thread [1] wasn't discussed, so here we go again. After 3 months, here's the situation reviewed : 1) - Notes posted : We receive about 30 notes a day, most of them are : I - Asking for help II - Pointing to a bug in the documentation (typo, something missing, etc..) III - Noise IV - Scripts to help other users Perhaps II could be handled if there were an option for the notes editors to submit the user note bug, the same way it is deleted/rejected/edited nowadays. I and III should be removed, and IV should be dealt on a case by case basis, some examples might be useful enough to make it into the manual entry's body. You mean I should be rejected (mail pointing to support resources), don't you ? 2) - Problems with the actual system : I - The rejection mail is too generic and deals with all the situations that may have caused the rejection. If the poster didn't read all the warnings while submitting the note (don't post support questions, don't, don't), will he really read such a mail ? Yep, it is a quick hack. The idea was that perhaps if the person did not read the first 2 times the info was shown, it might read the third time. It did decrease the number of junk when we started using that system, but I agree that maybe something more sophisticated is needed. More sophisticated and *shorter*. I think the big problem is that people are too leazy (most of them) and they are only ready to read a little text. II - We see some good notes deleted, and nothing done. We have lost one more occasion to provide a better manual. Agree. As you mentioned in IRC, I am all for having a way of labelling those entries to be added to the manual. III - When a note is deleted, we doesn't know why it was (from time to time I think that the one who deleted it don't know the reason..) That is true. Back when I had more time to help w/ the notes admin, there were cases were notes that were important were removed by a novice editor. IV - We sometime rejected notes with bad-formed emails, it only gives the mail server more work (and we know how the mail server suffers from time to time) Along w/ the rejection code, I had put some code to test the validity of the email, not just using regexes but also talking to the MX server to check that there was a real mailbox w/ that username, but that caused performance degradation in some cases. 3) - Solutions : First shot, solving I, II and III. Same as proposed in [1], but a little reviewed (three months has passed by) Possible actions : Rejected Deleted To be integrated Integrated No action (another maintainer will maybe take one of the four actions mentioned before) I would add: Send bug report Nice idea. We can use posttohost() here. Possible reasons : * Rejected : - bug : Didn't you read all the warnings before posting ? Please fill in a bug report. we can also mention features request here. - support : have a look at php.net/support.php - not our thing : Hey !! why is www.somesite.com pointing me here ???. Answer drop a mail to the webmaster of this site * Deleted : - trash : a note that doesn't belong in our manual at all (spam, irrelevant, wrong note, bad coded script, submitted twice, etc..). Everything that is not part of the other reasons for deleting a note. - integrated : the note is now in the official manual. We can also make the script send an automatic mail to the submitter (he will certainly be pleased) * to be integrated : - this note is really relevant and should be in our manual ? mark it as integrated. If you have enough time/karma, add it to CVS, then delete the note with integrated as reason If you don't have enough karma, but still want to help, write something and send it to phpdoc, someone will validate and integrate it. If you don't wanna do something more, stop here. A web interface will allow phpdoc'ers to see the notes flagged this way and they'll act for you. The integration bit could be done as a documentation bug report, with the advantage that there will be a track record of the action/contents. Agreed. This way we don't have to developp another interface to handle this. Second shot, solving IV : The actual system doesn't test the emails before sending a rejection mail. We can make it do so, with a regexp and testing if spam or remove is part of the email. This way, even if we make a mistake and click the bad link, the mail server won't be working in vain. Did someone modify the way the email is validated. Last time I saw it, it was using a regex. Might want to check if the regex has been changed or the validation omited altogether in the source code. Oups, seems like I have missed this part of the script :) 4) - Discussions : When I proposed [1] I recieved a lot of
Re: [PHP-DOC] Notes system (again)
Allowee wrote: On Tuesday 18 November 2003 00:35, Jesus M. Castagnetto wrote: --- Mehdi Achour [EMAIL PROTECTED] wrote: Hi ! It's been a while since the thread [1] wasn't discussed, so here we go again. After 3 months, here's the situation reviewed : 1) - Notes posted : We receive about 30 notes a day, most of them are I - Asking for help II - Pointing to a bug in the documentation (typo, something missing, etc..) III - Noise IV - Scripts to help other users Perhaps II could be handled if there were an option for the notes editors to submit the user note bug, Thats something I like. I've seen bug reports in the notes, that don't have an email address so I can't reject them.. I don't always have the time to directly fix it and it gets lots in the rest of the notes... I just say this note: Note that the config variable sybase.compatability_mode must be misspelled. In English, the word is spelled compatibility, so don't use your English knowledge. I think that this will be submitted as a doc bug. I took the time to check the source and there is nothing wrong. maybe the 'to be submitted as bug' should be re-checked to ensure that there are no bogus bug reports (I'm sure the doc and bug teams will be happy with that) I think this is the note editor task. A quick look on the note can make one say if it's a true bug, or bogus (as you did today). But one shouldn't bother himself if he don't have the time. A lot of bogus bug reports are posted daily.. it will only be another one. the same way it is deleted/rejected/edited nowadays. I and III should be removed, and IV should be dealt on a case by case basis, some examples might be useful enough to make it into the manual entry's body. 2) - Problems with the actual system : I - The rejection mail is too generic and deals with all the situations that may have caused the rejection. If the poster didn't read all the warnings while submitting the note (don't post support questions, don't, don't), will he really read such a mail ? Yep, it is a quick hack. The idea was that perhaps if the person did not read the first 2 times the info was shown, it might read the third time. It did decrease the number of junk when we started using that system, but I agree that maybe something more sophisticated is needed. II - We see some good notes deleted, and nothing done. We have lost one more occasion to provide a better manual. Agree. As you mentioned in IRC, I am all for having a way of labelling those entries to be added to the manual. I can only agree here.. But when there is a 'to be added to the manual' thing it will atleast help me finding the notes and manual files that I wanted to edit/add, but forgot about it after because I didn't have the time at that moment what about the idea of creating a new category of documentation bug and stuff this notes there ? IMHO, if we add something to the doc it's because it was missing. Even if it's an example or something not truelly bogus. I don't know if a lot of people will agree on this but let's try :) III - When a note is deleted, we doesn't know why it was (from time to time I think that the one who deleted it don't know the reason..) Adding a reason files is very handy to actually take a look at what your doing.. but it will take some more time.. it will only require paying more attention IMHO. That is true. Back when I had more time to help w/ the notes admin, there were cases were notes that were important were removed by a novice editor. IV - We sometime rejected notes with bad-formed emails, it only gives the mail server more work (and we know how the mail server suffers from time to time) Along w/ the rejection code, I had put some code to test the validity of the email, not just using regexes but also talking to the MX server to check that there was a real mailbox w/ that username, but that caused performance degradation in some cases. 3) - Solutions : First shot, solving I, II and III. Same as proposed in [1], but a little reviewed (three months has passed by) Possible actions : Rejected Deleted To be integrated Integrated No action (another maintainer will maybe take one of the four actions mentioned before) I would add: Send bug report what about the option on that page: Send General bug report (it has something to do with the function) Send Documentation bug report (somthing with the docs) I don't think we need all the sections that exist on bugs.php.net, do we? I agree, it's not a note maintainer task. Possible reasons : * Rejected : - bug : Didn't you read all the warnings before posting ? Please fill in a bug report. we can also mention features request here. - support : have a look at php.net/support.php - not our thing : Hey !! why is www.somesite.com pointing me here ???. Answer drop a mail to the webmaster of this site * Deleted : - trash : a note that doesn't belong in our manual at all
Re: [PHP-DOC] Notes system (again)
On Tue, 18 Nov 2003, Gabor Hojtsy wrote: The integration bit could be done as a documentation bug report, with the advantage that there will be a track record of the action/contents. Do you mean that user notes would be automatically turned into documentation bug reports if decided by a note admin? This sounds good to me :) Others will surely point out the downsides :) One huge downside is the bugs system didn't have such a task in mind when it was created, and a seperate system would be more useful and well used. Since we're talking about actually implementing the note maintainer system[1], I think said system should handle this and not bugs.php.net All the ideas in this thread[2] and other[3] threads seem to make this the desirable option. And this was discussed at the 2003 phpdoc meeting[4] and some interesting findings[5] came about. Because people agreed that non-CVS users should be able to maintain notes, this is yet another reason why bugs.php.net shouldn't get involved. [snip] One thing I always wanted (and wrote code that was never integrated for some reason), was to let notes editors register which manual sections/pages they would be interested in editing, that way he/she would only recieve the emails related to those sections (of course all the other notes will still go to the Notes mailing list). Last time this came up, it was said that there is not much note admin currently to handle the notes, and the notes could be handled 'efficiently enough' if the changes proposed by Mehdi would be implemented. At least this is what I can remmeber. Since I am not an active note maintainer, don't take this opinions seriously. Having an intuitive system that enhances the note maintainer process should help with this, and the proposed ideas for this sound good. First it'll only be for those with CVS accounts but sometime in the future (and depending on how it all goes) this should expand into the public where PHP CVS accounts are not required, just knowledge. On a related note, I've been away for awhile but am slowly working back into the fold, so I very well could have missed something on this topic in the last three or so months. Regards, Philip [1] http://marc.theaimsgroup.com/?l=phpdocm=99618446902193 [2] http://marc.theaimsgroup.com/?l=phpdocm=106045687304773 [3] http://marc.theaimsgroup.com/?l=phpdocm=106900270021114 [4] http://goba.hu/docmeeting_2003/ [5] http://cvs.php.net/co.php/phpdoc/RFC/2003_meeting_findings.txt
Re: [PHP-DOC] Notes system (again)
--- Mehdi Achour [EMAIL PROTECTED] wrote: Hi ! It's been a while since the thread [1] wasn't discussed, so here we go again. After 3 months, here's the situation reviewed : 1) - Notes posted : We receive about 30 notes a day, most of them are : I - Asking for help II - Pointing to a bug in the documentation (typo, something missing, etc..) III - Noise IV - Scripts to help other users Perhaps II could be handled if there were an option for the notes editors to submit the user note bug, the same way it is deleted/rejected/edited nowadays. I and III should be removed, and IV should be dealt on a case by case basis, some examples might be useful enough to make it into the manual entry's body. 2) - Problems with the actual system : I - The rejection mail is too generic and deals with all the situations that may have caused the rejection. If the poster didn't read all the warnings while submitting the note (don't post support questions, don't, don't), will he really read such a mail ? Yep, it is a quick hack. The idea was that perhaps if the person did not read the first 2 times the info was shown, it might read the third time. It did decrease the number of junk when we started using that system, but I agree that maybe something more sophisticated is needed. II - We see some good notes deleted, and nothing done. We have lost one more occasion to provide a better manual. Agree. As you mentioned in IRC, I am all for having a way of labelling those entries to be added to the manual. III - When a note is deleted, we doesn't know why it was (from time to time I think that the one who deleted it don't know the reason..) That is true. Back when I had more time to help w/ the notes admin, there were cases were notes that were important were removed by a novice editor. IV - We sometime rejected notes with bad-formed emails, it only gives the mail server more work (and we know how the mail server suffers from time to time) Along w/ the rejection code, I had put some code to test the validity of the email, not just using regexes but also talking to the MX server to check that there was a real mailbox w/ that username, but that caused performance degradation in some cases. 3) - Solutions : First shot, solving I, II and III. Same as proposed in [1], but a little reviewed (three months has passed by) Possible actions : Rejected Deleted To be integrated Integrated No action (another maintainer will maybe take one of the four actions mentioned before) I would add: Send bug report Possible reasons : * Rejected : - bug : Didn't you read all the warnings before posting ? Please fill in a bug report. we can also mention features request here. - support : have a look at php.net/support.php - not our thing : Hey !! why is www.somesite.com pointing me here ???. Answer drop a mail to the webmaster of this site * Deleted : - trash : a note that doesn't belong in our manual at all (spam, irrelevant, wrong note, bad coded script, submitted twice, etc..). Everything that is not part of the other reasons for deleting a note. - integrated : the note is now in the official manual. We can also make the script send an automatic mail to the submitter (he will certainly be pleased) * to be integrated : - this note is really relevant and should be in our manual ? mark it as integrated. If you have enough time/karma, add it to CVS, then delete the note with integrated as reason If you don't have enough karma, but still want to help, write something and send it to phpdoc, someone will validate and integrate it. If you don't wanna do something more, stop here. A web interface will allow phpdoc'ers to see the notes flagged this way and they'll act for you. The integration bit could be done as a documentation bug report, with the advantage that there will be a track record of the action/contents. Second shot, solving IV : The actual system doesn't test the emails before sending a rejection mail. We can make it do so, with a regexp and testing if spam or remove is part of the email. This way, even if we make a mistake and click the bad link, the mail server won't be working in vain. Did someone modify the way the email is validated. Last time I saw it, it was using a regex. Might want to check if the regex has been changed or the validation omited altogether in the source code. 4) - Discussions : When I proposed [1] I recieved a lot of feedbacks saying : wow, too many reasons, it's gonna be horrible. This is how the alert sent to the notes mailing list will look like Submitter email The note Manual page Delete : trash Integrated Reject : bug support
Re: [PHP-DOC] Notes system (again)
Hmm, this seems to be a good idea to me. The more information gathered about these things the better. As per those who are too lazy for such a system; why are you on the phpdoc team in the first place? Mehdi Achour wrote: Hi ! It's been a while since the thread [1] wasn't discussed, so here we go again. After 3 months, here's the situation reviewed : 1) - Notes posted : We receive about 30 notes a day, most of them are : I - Asking for help II - Pointing to a bug in the documentation (typo, something missing, etc..) III - Noise IV - Scripts to help other users 2) - Problems with the actual system : I - The rejection mail is too generic and deals with all the situations that may have caused the rejection. If the poster didn't read all the warnings while submitting the note (don't post support questions, don't, don't), will he really read such a mail ? II - We see some good notes deleted, and nothing done. We have lost one more occasion to provide a better manual. III - When a note is deleted, we doesn't know why it was (from time to time I think that the one who deleted it don't know the reason..) IV - We sometime rejected notes with bad-formed emails, it only gives the mail server more work (and we know how the mail server suffers from time to time) 3) - Solutions : First shot, solving I, II and III. Same as proposed in [1], but a little reviewed (three months has passed by) Possible actions : Rejected Deleted To be integrated Integrated No action (another maintainer will maybe take one of the four actions mentioned before) Possible reasons : * Rejected : - bug : Didn't you read all the warnings before posting ? Please fill in a bug report. we can also mention features request here. - support : have a look at php.net/support.php - not our thing : Hey !! why is www.somesite.com pointing me here ???. Answer drop a mail to the webmaster of this site * Deleted : - trash : a note that doesn't belong in our manual at all (spam, irrelevant, wrong note, bad coded script, submitted twice, etc..). Everything that is not part of the other reasons for deleting a note. - integrated : the note is now in the official manual. We can also make the script send an automatic mail to the submitter (he will certainly be pleased) * to be integrated : - this note is really relevant and should be in our manual ? mark it as integrated. If you have enough time/karma, add it to CVS, then delete the note with integrated as reason If you don't have enough karma, but still want to help, write something and send it to phpdoc, someone will validate and integrate it. If you don't wanna do something more, stop here. A web interface will allow phpdoc'ers to see the notes flagged this way and they'll act for you. Second shot, solving IV : The actual system doesn't test the emails before sending a rejection mail. We can make it do so, with a regexp and testing if spam or remove is part of the email. This way, even if we make a mistake and click the bad link, the mail server won't be working in vain. 4) - Discussions : When I proposed [1] I recieved a lot of feedbacks saying : wow, too many reasons, it's gonna be horrible. This is how the alert sent to the notes mailing list will look like Submitter email The note Manual page Delete : trash Integrated Reject : bug support not our thing To be integrated Search the note database 6 possibilities. IMHO, if someone found this to be too many, he doesn't belong on the notes maintainers staff as he don't want to put forth any effort. A note maintainers task is to take care of the manual and improve it. It requires effort (private joke : rioter... I'm sorry =D) 5) - Active maintainers : Here are the list of the active maintainers for last months : - Vincent Gevers (vincent) - Sebastian-H. Picklum (sp) - Mehdi Achour (me, didou) - Sara Golemon (pollita) Managing the notes every day, integrating notes in the manual, fixing the bugs reported there. - Jani Taskinen (sniper) : As he's in the front line in the bugs reports, he sometimes walks through a manual page after closing a related bug and hunts down most of the notes there. There's some people who help from time to time and people who have helped a lot in the past. We can mention jimw, ronabop, zak, alindeman, jmc, betz, phillip.. (sorry for whoever I'm forgetting) I would really like to hear feedback from all of you. Sure, everyone else is welcome, especially phpdoc'ers for the to be integrated proposition. 6) - Conclusions : I hope this time the thread won't die. I'm ready to developp the new interface and the help of everyone is again welcomed. The ball is in your camp, shoot it back ! Best regards, Mehdi Achour --- [1] ::
Re: [PHP-DOC] Notes system (again)
Submitter email The note Manual page Delete : trash Integrated Reject : bug support not our thing To be integrated Search the note database Seems to be fine with me. The URLs need to be shorter and more clear IMHO. It would be nice to set up a 404 handler on master.php.net, so we would be able to do tricks there for these kind of URLs. I don't think that it would be a good idea to abuse the PHP.net shortcut namespace for these shortcuts. Goba
Re: [PHP-DOC] Notes system (again)
Gabor Hojtsy wrote: Submitter email The note Manual page Delete : trash Integrated Reject : bug support not our thing To be integrated Search the note database Seems to be fine with me. The URLs need to be shorter and more clear IMHO. It would be nice to set up a 404 handler on master.php.net, so we would be able to do tricks there for these kind of URLs. I don't think that it would be a good idea to abuse the PHP.net shortcut namespace for these shortcuts. Fine with me too. didou
