cvs: phpdoc /howto howto.xml working.xml

alindeman Tue May 6 18:12:03 2003 EDT Modified files: /phpdoc/howto howto.xml working.xml Log: adding a note guidelines section Index: phpdoc/howto/howto.xml diff -u phpdoc/howto/howto.xml:1.38 phpdoc/howto/howto.xml:1.39 --- phpdoc/howto/howto.xml:1.38 Sat May 3 15:53:48 2003 +++ phpdoc/howto/howto.xml Tue May 6 18:12:03 2003 @@ -17,9 +17,6 @@ ]> <!-- TODO - - On user note editing: - http://marc.theaimsgroup.com/?l=phpdoc&m=105199111308515&w=2 Quickrefs: http://www.mulberrytech.com/quickref/index.html Index: phpdoc/howto/working.xml diff -u phpdoc/howto/working.xml:1.26 phpdoc/howto/working.xml:1.27 --- phpdoc/howto/working.xml:1.26 Sat May 3 10:45:22 2003 +++ phpdoc/howto/working.xml Tue May 6 18:12:03 2003 @@ -1196,6 +1196,74 @@ <literal>php-notes</literal>). This list is the place where all the manual notes are posted. You may consider subscribing to this mailing list if you would like to help manage the notes. + See the next section for more information on note editing guidelines. + </para> + </chapter> + + <chapter id="chapter-user-notes"> + <title>User Note Editing Guidelines</title> + + <para> + These are some guidelines to follow when editing user notes in the manual. + </para> + <para> + 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. + <itemizedlist> + <listitem> + <simpara> + 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. + </simpara> + </listitem> + <listitem> + <simpara> + If the note contains useful information appropriate for the manual proper, + you may incorporate the information into the manual and then 'delete' the + note. + </simpara> + </listitem> + <listitem> + <simpara> + 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. + </simpara> + </listitem> + <listitem> + <simpara> + If the note submitter's email address is obviously bogus, don't reject the + note. This just gives the mail server more work trying to send an email to + a non-existant address, which doesn't help anything. + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + If for some reason you need to add to a note, first as 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 + 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. + </para> + <para> + If you have some free time and commit access to php-doc, 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. + </para> + <para> + If you are in doubt about what to do with a note, you may ask for help on the + php-notes mailing list (or php-doc, if what you're doing involves the documentation + proper). </para> </chapter>