On 11 March 2012 02:40, Jesus M. Castagnetto <je...@castagnetto.com> wrote:
> Sorry to come so late in this discussion. But there are guidelines for > more than a decade on how to handle notes: > > http://doc.php.net/php/dochowto/chapter-user-notes.php > > Just in case you did not see it: > > User Note Editing Guidelines > > These are some guidelines to follow when editing user notes in the manual. > > To begin editing user notes in the manual, you must have SVN commit access > to the manual, and you must either: > Subscribe to the *php-notes* mailing list or newsgroup as described at Mailing > Lists, Newsgroups and SVN > Modules<http://doc.php.net/php/dochowto/chapter-maillist.php>. > As a user submits a new user note, it will appear as a message on the > mailing list with links in the footer of the email that enable you to > delete, edit, or reject that particular note. > Log on to the server at » > http://master.php.net/manage/user-notes.php<http://master.php.net/manage/user-notes.php> > using > your SVN user ID and password. The user notes administration interface > enables you to search for user notes that match particular strings and edit > or change the status of particular notes directly through the Web interface. > > The thing that seems to confuse the most people is the difference between > 'rejecting' and 'deleting' a note. Basically, they both remove the note > from the manual, but 'rejecting' sends the user an email about the > rejection with links to support links and other information. Here are some > guidelines of when to use each. This section is mostly an edited version of > Jesus M. Castagnetto's email, with a few additions and re-phrases. The code > for managing user notes can be seen here: » > http://svn.php.net/viewvc/web/php-master/trunk/manage/user-notes.php<http://svn.php.net/viewvc/web/php-master/trunk/manage/user-notes.php>. > You can also view the exact text of the rejection email there. > > > - If the note is asking for help (support request, 'Does this > work...?', etc.) or if the person is reporting a bug, 'reject' the note. > The email will show them the proper place to report such issues. > - If the note contains useful information appropriate for the > manual proper, you may incorporate the information into the manual and > then > 'delete' the note. > - If the note is in the wrong place, incorrect, a giant block of > silly, unnecessary code, poorly written, an answer to another person's > question, or just overall confusing, 'delete' it. If it was an answer > to a > question, hunt down that note and 'reject' it. > - If the note is in a language other than English, 'delete' the > note. > - If the note submitter's email address is obviously bogus, don't > 'reject' the note, just 'delete' it. Rejecting the note just gives the > mail > server more work trying to send an email to a non-existent address, > which > doesn't help anything. > > If for some reason you need to add to a note, first ask yourself if it's > worth it. Make sure you're not answering a user's question; if you are, > then the note doesn't belong there (see above). If you're clarifying a > point, see if it is appropriate to add the clarification to the manual > proper; if it is, add it and 'delete' the note (see above). If you still > feel that adding your addition to the note will be the best option, then go > ahead and add it. Usually, editors add their note in a "Editor's Note" > block at the top. Unless you are correcting a minor error, make it obvious > that you edited the note. > > If you have some free time and commit access to phpdoc, try going through > some of the manual pages and adding some of the better notes into the > documentation proper. Be sure to 'delete' these notes after they're > implemented. > > If you are in doubt about what to do with a note, you may ask for help on > the php-notes mailing list (or phpdoc, if what you're doing involves the > documentation proper). > > > > Hi Jesus, I know those guidelines exist, I even linked to them from my original post. However, those guidelines aren't very complete. They give a very rough overview, which I agree with completely. There are tons of notes however, which fall somewhere in between the categories supplied in the guidelines. What I'm mainly trying to say is that I personally think we don't need a zillion examples of how to use a basic function to perform a specific task. Most notes (these days) contain such code. Some are still quite general (ie. people post an example of how preg_split can be used to limit a sentence to a number of words), others are extremely specific (ie. I've seen posts where people show a function to the amount of days between carnival and easter) or possibly numerous with a little usefulnus, but mainly a lot of cluttering (ie. people post date() monthnames in different languages, spanish, russian, chinese, french, german, etc. There were at least 30 of these last time I checked. Too many to add as an example, and so many that they obscure other notes). My problem with all this is that it's usually not general enough to integrate into the manual itself. Because when I view the manual, I want to know how a function works, I don't care for an extremely specific use of the function for a task that I don't even understand by itself. The second problem I have with such things is that there are simply too many notes for certain functions present in my opinion. When you have more than 100 notes(!!) on a single page, finding the one thing you want is neigh impossible. Ronald argued against this, while I think it is important to moderate them more strictly and keep not only the manual itself, but also the notes, more readable. I was hoping this last part would spark some more discussion, but unfortunately, it has not. - Tul >
