On Apr 6, 2010, at 9: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?
At one point in time that wasn't a TOC, as instead it contained all those sub-sections on one page. The notes remained there, however. There are tools to move around notes (even entire pages of notes), and scripts to find orphaned notes, but honestly user notes has become a low priority to most everyone. Sad, but true. > > 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. That's was the original idea, and once worked well. However, over time we started leaving information that looked remotely useful so it's grown [out of control]. And besides, it's difficult to know what a proper user note is as I reckon we all have different definitions. And over time users have come to expect the user notes as is, which are remotely related tips and code snippets. I think simply removing them all would cause the PHP world to crash upside down. :) All thoughts and ideas welcome. Regards, Philip
