Chapter 11. 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 CVS commit access to the manual, and you must either:

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://cvs.php.net/co.php/php-master-web/manage/user-notes.php. You can also view the exact text of the rejection email there.

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).