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
