--- Stas Bekman <[EMAIL PROTECTED]> wrote: > 2) docs need to have user comments. > > I'm not sure it's a good idea. We already have a way too much > documentation. Instead of making it even harder for users to find > things, one should take the existing docs and improve them, rather > then dump random comments in there. If you want to add a comment, > that means that something is not clearly explained.
This is true, but I don't think it discounts the merit in having user comments. One of the best features of the PHP manual is the user comments, and it's helpful for those weird scenarios that maybe only a couple of developers encounter. It also encourages more people to contribute. While it would be nice to think that anyone with a contribution to make would submit a documentation patch, I think you'll find that giving people an easy form to add a comment results in much more feedback, and other developers who reference the manual seem to really appreciate some of this random insight. A good approach to take with user comments is actually to try to get rid of them (I know, it sounds contradictory). You basically want to delete the ones that aren't valid and integrate the valid ones into the documentation itself. Sometimes those who write the documentation may not have thought of something, and a good user comment can make documentation maintenance much easier. So, while user comments may not be the best idea, I don't think it is an idea that is completely without merit. Of course, as you suggest, ideas are cheap (mine included). Suggesting user comments would be much better bundled with some code. :-) Chris -- Report problems: http://perl.apache.org/bugs/ Mail list info: http://perl.apache.org/maillist/modperl.html List etiquette: http://perl.apache.org/maillist/email-etiquette.html
