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). Cheers -- Jesus M. Castagnetto <je...@castagnetto.com> Web: http://www.castagnetto.com/ On Fri, Feb 24, 2012 at 17:32, Maciek Sokolewicz < maciek.sokolew...@gmail.com> wrote: > On 24-02-2012 23:12, Ronald Chmara wrote: > >> On Fri, Feb 24, 2012 at 1:54 PM, Maciek Sokolewicz >> <maciek.sokolew...@gmail.com> wrote: >> >>> The reason I'm using such "strict" guidelines is simply >>> to make the manual notes readable. If you look at a page such as >>> http://www.php.net/manual/en/**function.strtotime.php<http://www.php.net/manual/en/function.strtotime.php>, >>> there are> 100 notes >>> present. Trying to find something useful to you is simply impossible on >>> such >>> a page. >>> >> >> I disagree. The problem is not that there are too many notes. (That's >> a bit like complaining the internet has too many pages). The problem >> on that page is that strtotime isn't documented in such a way as to >> make the many notes unnecessary. >> > > I disagree, see below why. > > >> Trying to clean that page to only leave samples that solve very >>> common problems or clarify the behaviour of the function is IMO a good >>> thing. That does often mean removing various code samples of the type >>> "this >>> might be useful to some people". >>> >>> I am wondering what others think, should we try to thin down the stream >>> of >>> notes and simply delete notes that have little to say about the actual >>> function or are of relatively little use to the common PHP coder? Or >>> should >>> we leave as many notes as possible with examples so people can find >>> *anything* in there? Possibly leading to unwieldy long lists of notes? >>> >>> What do YOU think? Feel free to comment / criticise / be constructive ;) >>> >> >> Notes, to me, are an indication of what is lacking in the manual. If >> you want to delete a note, make sure the content/idea/concept has >> already been put into the documentation somehow. Update the >> documentation, *then* delete the note. Simply deleting a note adds no >> value to the project. A page with many notes is a page in need of a >> re-write, not a note purge. >> >> -Ronabop >> > > I agree that many notes may mean that the documentation is not explenatory > enough, that is IMO not always the case. If you look at the strtotime page, > you would be adding the following examples to the manual: > > - how to make "strotime work with dates prior to 1970" > - how "next month" is interpreted in edge cases > - the fact that mm/dd/yyyy is a US date format, while dd/mm/yyyy is a > european format > - weeks start on sunday > - how to parse dates stored in MySQL > - how to calculate the time passed since a certain date (ie. timediff) > - how to loop through date ranges > - possible misunderstandings in the interpretation of dates by strotime > - the fact that you have to escape modifiers > - how to "add time" using strtotime > - how to handle specific time formats using strtotime > - how to calculate bank holidays > - how to convert dates from some specific format to another > - the fact that strtotime produces different output on 32bit machines than > it does on 64bit > - workarounds to make a different day the first day of the week > > etc. > Some of these, I agree, should indeed be added to the manual. However, > many are simply showing possible ways to work with the function. Not > something that many people would *need*. The documentation is IMO not a > place to hold every possible use of the function. It's a place where you go > to find out how it works, and in the notes any interesting sidenotes about > why it may not work as expected. > Examples are added to clarify how to work with the function, but providing > every possible way of using it (potentially millions) is simply not useful. > > My other point is that such spam drowns out the useful notes, such as the > one explaining differences in function behaviour between 32bit and 64bit > systems. Instead you find a zillion notes explaining how you can emulate > behaviour of other functions using this one. > >
