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)
