Re: User commentary in docs

On Apr 6, 2010, at 12:56 PM, Philip Olson wrote:

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.

I think that in an ideal world, the comments all get integrated, and then deleted. This is impractical, given the sheer scope of the problem, but it's an ideal to strive towards, and an excellent place to point folks who want to get involved in the documentation process. --Rich