Re: Interactive docs idea

Alvaro Herrera <alvherre@dcc.uchile.cl> writes:

> On Thu, Apr 14, 2005 at 01:39:11PM -0400, Greg Stark wrote:
> 
> > I think the idea of moderating the comments is inherently flawed. You can
> > either have the deliberate, planned documentation without the comments, or you
> > can have the wild-west style comments system, but trying to have it both ways
> > is impossible. It just leads to the current situation where the comments are
> > moribund.
> 
> What do you mean, moribund?  What happens is that at each release Tom
> gets the comments and integrate whatever of value into the main text
> body.  The rest are deleted.

So there's no comments saying "here's a useful function written using this
function" or "watch out for this common bug" or "if what you want to do is
this you might want to check out this other function" or any of the thousands
of similar comments in the PHP docs.

Instead you get one good example that's worthy of being included in the
documentation and nothing else.

There's also a problem that people are less likely to put comments in if they
don't see any existing comments.

-- 
greg