Re: User commentary in docs

On 04/06/2010 09:41 AM, Robert P. J. Day wrote: > On Tue, 6 Apr 2010, Rich Bowen wrote: > >> A few of us on the Apache HTTP Server documentation team are >> investigating what it would take to add a user commentary system to >> the Apache HTTPD docs, like that used on the PHP docs. What software >> is used for that? Is it easily reusable in other places? Where can I >> get some more info about it? > > please reconsider that idea. as it is, there's simply too much > nonsense that's been added by users at the PHP docs site. here's an > example: > > http://www.php.net/manual/en/language.variables.php > > if you look closely at that page, it's simply a ***table of > contents***, fer cryin' out loud. nevertheless, numerous commenters > found it necessary to expound on it. for what conceivable purpose? > > if you want to support user commentary, the only sane way is to > regularly peruse those comments, trash the garbage, and incorporate > the reasonable comments into the documentation proper. just leaving > the comments there in perpetuity is, IMHO, a terrible idea. Robert, you could pitch in and help clean up and incorporate the comments then. I am sure Dan and the others would appreciate the help. There is simply too much user feedback and too few volunteers to get them all into the documentation in a timely manner. We found long ago that the best alternative was to have a quick way to get rid of bad comments and let the majority of stuff through because there really is some good contents in there. You may not like them, but I can tell you that the huge majority of feedback we get on them is positive. Almost everywhere I go, no matter where it is in the world, the user comments in the documentation is something people say they love about PHP. -Rasmus