Re: Interactive docs idea

On Thu, Apr 14, 2005 at 03:01:10PM -0400, Greg Stark wrote:
> 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.

You are right, there aren't.  But to me that's not a bad thing.  I'd
find PHP's manual much better if the main text body really covered the
subject instead of only showing a couple of examples, and leaving part
of the matter to the comments  (Even to "editor's notes" in the
comments!)

> 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.

I have agree with you on this last assertion.

-- 
Alvaro Herrera (<alvherre[@]dcc.uchile.cl>)
"Postgres is bloatware by design: it was built to housePhD theses." (Joey Hellerstein, SIGMOD annual conference 2002)