Re: Interactive docs idea

On Thu, Apr 14, 2005 at 03:01:10PM -0400, Greg Stark wrote:
> Alvaro Herrera <alvherre(at)dcc(dot)uchile(dot)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[(at)]dcc(dot)uchile(dot)cl>)
"Postgres is bloatware by design: it was built to house
PhD theses." (Joey Hellerstein, SIGMOD annual conference 2002)