--- 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. :-)
Sure, it's perfectly reasonable. But nothing prevents those users from posting those comments to the list and then they will be integrated into the docs.
This kind of approach is useful for those rare cases, when a solution is not a generic one. For most users it's much better to have less docs, to be more digestible.
Alternatively, someone may want to start a wiki project where people can dump anythings they want, and then we can merge some of those notes back into the docs.
-- __________________________________________________________________ Stas Bekman JAm_pH ------> Just Another mod_perl Hacker http://stason.org/ mod_perl Guide ---> http://perl.apache.org mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com http://modperlbook.org http://apache.org http://ticketmaster.com
-- 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
