Re: Interactive docs idea

From: Alvaro Herrera
Subject: Re: Interactive docs idea
Date: ,
Msg-id: 20050414190938.GF28198@dcc.uchile.cl
(view: Whole thread, Raw)
In response to: Re: Interactive docs idea  (Greg Stark)
Responses: Re: Interactive docs idea  (Greg Stark)
List: pgsql-hackers

Tree view

Interactive docs idea  (Christopher Kings-Lynne, )
 Re: Interactive docs idea  (Alvaro Herrera, )
  Re: Interactive docs idea  (Greg Stark, )
   Re: Interactive docs idea  (Christopher Kings-Lynne, )
    Re: Interactive docs idea  (Andrew Dunstan, )
 Re: Interactive docs idea  ("Dave Page", )
  Re: Interactive docs idea  (Robert Treat, )
   Re: Interactive docs idea  (Alvaro Herrera, )
  Re: Interactive docs idea  (Greg Stark, )
   Re: Interactive docs idea  (Alvaro Herrera, )
    Re: Interactive docs idea  (Greg Stark, )
     Re: Interactive docs idea  (Alvaro Herrera, )
      Re: Interactive docs idea  (Greg Stark, )
   Re: Interactive docs idea  ("Joshua D. Drake", )
 Re: Interactive docs idea  ("Dave Page", )
  Re: Interactive docs idea  ("Jim C. Nasby", )

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



pgsql-hackers by date:

From: Tom Lane
Date:
Subject: Re: [PATCHES] NetBSD mac68k crashing on union regression test
From: Tom Lane
Date:
Subject: Re: OUT parameters in PL/Java