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 (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
Sure, we can add an icon with a little bug (insect) inside as long as the other icons, this way people working on a manual page like Jani will only have to keep clicking on this icon.
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 :)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 0keliglia.com%3E
PS : Thank you for the review Lateralus ;)
===== --- Jesus M. Castagnetto <[EMAIL PROTECTED]>
__________________________________ Do you Yahoo!? Protect your identity with Yahoo! Mail AddressGuard http://antispam.yahoo.com/whatsnewfree
