Re: Comments for the manual

--- Tobias Schlitt <tobias@schlitt.info> wrote: > Hi PEARs! > > I'd like to implement a comment system for the > online manual and > therefor send you my ideas to do this (to be > corrected by you, cause > this is you stuff). > > The comment system should basically look like the > one on php.net. A > comment can be added by anyone visiting the manual, > but has to be > approved by a) the maintainer of the package b) a > pearweb admin before > it is displayed. When a comment is approved it is > instantly visible to > the users. You can just borrow the whole code from php.net and use that. Just make sure that you use the correct ACL for the users allowed to edit the comments, which in this case should be a PEAR developer, or we can create the pear.doceditor option for an account perhaps. > I do not want to make this with multi language > support to, to bundle the > comments in english on each online manual page. This > encloses package > individual manual pages (here the package maintainer > or a pearweb admin > can edit this intries) but all other pages under > http://pear.php.net/manual/<lang>/ dir structure > (only pearweb admins > can edit this entries), too. Hmm, not sure what multilanguage support will bring. In PHPDOC, the localized notes are associated w/ the language of the manual with addition to the english notes from the main manual, i.e. the 'de' manual will have the notes in german + the ones that were added to the 'en' manual. > Each comment post results in a report email to > either the specific > package team or (on general pages) to > pear-webmaster@php.net and/or > pear-doc mailinglist. For the php manual there is the php-notes mailing list to which all the people who want to act as editors must subscribe. That gets sent and email w/ quick links to edit, remove, or reject an entry. A rejection will remove the entry and send an (boilerplate) email to the originator listing the reasons why his/her contribution has been rejected. > A user allowed to edit comments on a manual page > will see not approved > entries (colorized) and can edit, delete or > instantly accept these and > all accepted comments on this page as well. Hmm, moderation might not work once the volume of notes is high enough (as in the PHP manual). The approach there is that a note does not get live until a certain period of time, that gives some leeway to the editors to edit/remove/reject the note before it goes live. Of course you can also perform those editor activities once the note is live. An option that would be good for editors will be to mark a note as a candidate to be added in the body of the manual (eg. a very good example or a clearer/more complete explanation of a method/class), perhaps when an editor hits that option, the note gets automagically submitted as a PEARDOC bug, that way someone will notice it and add it to the appropriate page. > Editing here means to change the text of a proposal, > to accept or delete > it, but even to move 1 or all comments from a page > to another page. For > pearweb admins there is additionally the posibillity > to view a summary > of all open (not accepted comment) and unassigned > (page deleted??) > comments and can edit those. Note sure about all that moderation, being able to go to a page and perform edits should be enough. Otherwise you will be duplicating a structure/association that already exist in the manual. Also, I am not clear on when you will need to move all notes from one page to another. Moving one is a simple as adding a new one in the correct page w/ the info from the originator (which an editor can see) and then removing the original, usually we used to add an "[Editor note: ...]" at the top of the modified/moved content. > During generation of the docs comment assignments > are checked and error > reports will be send to pear-doc mailinglist and > pear-webmaster. Hmm, that might swamp the pear-doc eventually, if it ever gets to the volume of the notes the main PHP manual recieves. Most of the notes end up being bogus, requests for help, etc. which are not good contributions. For details see: http://marc.theaimsgroup.com/?l=phpdoc&m=105199111308515&w=2 That info is not part of the "PHPDOC Howto": http://www.php.net/manual/howto/chapter-user-notes.html At some point I wrote some code to allow editors to "subscribe" to a particular manual page and recieve emails each time a page had a note added, that was eons ago when I implemented the "reject" option (much improved by others afterwards). See: http://cvs.php.net/cvs.php/php-master-web/include/alert_lib.inc and http://cvs.php.net/cvs.php/php-master-web/manage/notes-alert.php (old simple code, sure can be improved). > I hope you like these ideas. > > Regards, > Toby > > -- > PEAR Documentation List Mailing List > (http://pear.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > ===== --- Jesus M. Castagnetto <jmcastagnetto@php.net> __________________________________ Do you Yahoo!? Yahoo! Hotjobs: Enter the "Signing Bonus" Sweepstakes http://hotjobs.sweepstakes.yahoo.com/signingbonus