I think the comments should stay, but improve the functionality to make them more useful/constructive.
Develop a upvote/downvote system for comments. This should eliminate stupid comments from wasting people's time, and the popular comments should indicate what parts of the manual could be improved. The good comments could even be visible on the page by default instead of hidden. Although I understand your suggestion that people should just edit the manual to include what they're suggesting, some people: a) might not want to impose their code on others (beginners might be unsure what is the best way to do something and don't want to mislead others) b) might be too lazy to contribute something of value, due to language barriers or lack of ability to write meaningful prose I'm sure we all agree that reading through the user comments in the PHP manual is a great source of WTF fodder, but there are some serious gems in there that have saved my butt a ton of times. Cheers, Adam AD7six wrote: > Hi All, > > Before doing anything rash I'd like to ask the community: Is the > possibility to add comments to the book doing more harm than good? > Should the possibility to add comments be removed? > > The main reason for asking is that, although things have improved > lately, many comments should have been submitted as corrections or > additions to the contents. Some examples to illustrate (the goal is > examples, not finger pointing/witch hunting): > > Should have been a ticket: > http://book.cakephp.org/comments/3#comment_562 > > Should have been an edit: > http://book.cakephp.org/comments/index/162/Localizing-Your-Application#comment_510 > > Should maybe have been a post here: > http://book.cakephp.org/comments/index/162/Localizing-Your-Application#comment_641 > > Trying to talk to Admins: > http://book.cakephp.org/comments/29#comment_536 > > Talking to yourself: > http://book.cakephp.org/comments/566#comment_462 > > Should not have started reading at the end of the manual: > http://book.cakephp.org/comments/index/449 > > Misleading: > http://book.cakephp.org/comments/index/449#comment_639 > > Flat out wrong: > http://book.cakephp.org/comments/index/449#comment_574 > > Vampy: > http://book.cakephp.org/comments/95#comment_529 > > Etc. > > Probably the biggest problem with adding comments (and users who speak > more than one language will have already noticed this) is: if it's > actually useful - the translations have absolutely not indication of > whatever nugget of information unless it is submitted as an edit to > the contents. > > If you're familiar with the book's source (http://thechaw.com/ > cakebook) you'll know that there are some things coming to help guide > users to channel their efforts to be more effective, what else/more > should be done to further improve things in this regard? > > On topic suggestions on a postcard please, > > AD > PS. No how-the-book-should-work wishlist hijacking please (RFC/ > enhancement tickets as appropriate http://thechaw.com/cakebook/tickets > OR fork, implement your functionality and ask for it to be integrated) > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "CakePHP" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/cake-php?hl=en -~----------~----~----~----~------~----~------~--~---
