

> -----Original Message-----
> From: Neil Conway [mailto:neilc@samurai.com] 
> Sent: 02 February 2003 20:52
> To: Dave Page
> Cc: PostgreSQL Hackers
> Subject: Re: [HACKERS] Interactive Documentation - how do you 
> want it towork?
>
> > 2) Bearing in mind your answer to the previous question, should all 
> > the comments be deleted when useful examples have been 
> merged into the 
> > main documents (remember that the definition of 'useful' 
> may vary), or 
> > should we only remove the 'junk' ones?
> 
> Once the comment's suggestion has been incorporated and the 
> docs updated, I think it should be removed. Just like in the 
> rest of the documentation, there's no point presenting 
> duplicate content to the user, so we should only keep the 
> idocs comments that are still relevant. The same goes for 
> comments that have no value (e.g. support requests).

My concern here is that what (for example) Bruce decides is not a useful
addition to the docs themselves, maybe something that would have helped
me with some bizarre problem. If we dump *all* the docs after they have
been merged then I might lose that helpful tip.

Also, and perhaps more importantly, the comments will be merged into a
*future* version. If I am running 7.2, I'm going to look at the 7.2
docs, not 7.3.

Regards, Dave.

Sun, 2 Feb 2003 21:26:46 -0000
"Dave Page" <dpage@vale-housing.co.uk>
Re: Interactive Documentation - how do you want it towork?
Dave Page wrote:
> My concern here is that what (for example) Bruce decides is not a useful
> addition to the docs themselves, maybe something that would have helped
> me with some bizarre problem. If we dump *all* the docs after they have
> been merged then I might lose that helpful tip.
> 
> Also, and perhaps more importantly, the comments will be merged into a
> *future* version. If I am running 7.2, I'm going to look at the 7.2
> docs, not 7.3.

We have already had several eyes look at the comment, so I am fairly
certain that there isn't anything useful.  If there is, someone else
will make the same comment, and we will catch it.  Ideally, we would
have no comments because it would all be in the docs.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Sun, 2 Feb 2003 20:03:02 -0500 (EST)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: Interactive Documentation - how do you want it towork?

I don't think I was clear before.  When someone is looking at the
interactive docs, I would like them to say, "Oh, there's a comment.  I
better read that in case it will help me."  If we have old comments,
their "special" value becomes diminished.  That's why I think they
should be removed as they are reviewed.

---------------------------------------------------------------------------

Dave Page wrote:
> 
> 
> > -----Original Message-----
> > From: Neil Conway [mailto:neilc@samurai.com] 
> > Sent: 02 February 2003 20:52
> > To: Dave Page
> > Cc: PostgreSQL Hackers
> > Subject: Re: [HACKERS] Interactive Documentation - how do you 
> > want it towork?
> >
> > > 2) Bearing in mind your answer to the previous question, should all 
> > > the comments be deleted when useful examples have been 
> > merged into the 
> > > main documents (remember that the definition of 'useful' 
> > may vary), or 
> > > should we only remove the 'junk' ones?
> > 
> > Once the comment's suggestion has been incorporated and the 
> > docs updated, I think it should be removed. Just like in the 
> > rest of the documentation, there's no point presenting 
> > duplicate content to the user, so we should only keep the 
> > idocs comments that are still relevant. The same goes for 
> > comments that have no value (e.g. support requests).
> 
> My concern here is that what (for example) Bruce decides is not a useful
> addition to the docs themselves, maybe something that would have helped
> me with some bizarre problem. If we dump *all* the docs after they have
> been merged then I might lose that helpful tip.
> 
> Also, and perhaps more importantly, the comments will be merged into a
> *future* version. If I am running 7.2, I'm going to look at the 7.2
> docs, not 7.3.
> 
> Regards, Dave.
> 
> ---------------------------(end of broadcast)---------------------------
> TIP 2: you can get off all lists at once with the unregister command
>     (send "unregister YourEmailAddressHere" to majordomo@postgresql.org)
> 

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Sun, 2 Feb 2003 20:09:23 -0500 (EST)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: Interactive Documentation - how do you want it towork?