Re: Notes system (again)

On Tuesday 18 November 2003 00:35, Jesus M. Castagnetto wrote: > --- Mehdi Achour <didou@keliglia.com> 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 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. I'm a big +1 for this. bugs.php.net is to keep track of the problems. it will also avoid that doc'ers change something that is not true. on bugs.php.net there will be added a comment and marked as bogus > > > 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 > > 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) > > I don't think it is a problem (I am even suggesting > more options ;-) 6 options isn't a problem.... it's nothing compared to the bug emails > > > 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. how is this going to work with 2:III? I think people like Jani should get 'special' access. I don't think you'll like it to enter a reason hunderd times > > > > 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. > > +1 on the ideas in your proposal. Look also at the > suggestions above and the ones given by Goba. I'm also +1 on this. It will take a little bit more time for the actions, but If we can improve the manual with that it won't be a waste of time :) - Vincent > > 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 ! > > I would say, go ahead and look at the existing code > and start planning for modifications. Back when I > added the kludgy 'reject' (later improved by several > others), I showed a crude working code and that helped > focus the discussion. > > 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). > > > Best regards, > > > > Mehdi Achour > > > > --- > > > > [1] :: > > > http://news.php.net/article.php?group=php.doc&article=%3C3F35958D.4030008%4_\¤I > föjÔ
Çí×Ú° >0keliglia.com%3E > > > PS : Thank you for the review Lateralus ;) > > ===== > --- Jesus M. Castagnetto <jmcastagnetto@php.net> > > __________________________________ > Do you Yahoo!? > Protect your identity with Yahoo! Mail AddressGuard > http://antispam.yahoo.com/whatsnewfree