Re: Interactive Documentation - how do you want it towork? - Mailing list pgsql-hackers

Hi Bruce,

Have you ever used the idocs on the PHP site? I find them invaluable,
though there are many useful comments that you might not want to
incorporate into the official docs for fear of bloating them. Take a
look at http://www.php.net/manual/en/function.intval.php for example.

Regards, Dave.


> -----Original Message-----
> From: Bruce Momjian [mailto:pgman@candle.pha.pa.us]
> Sent: 03 February 2003 01:09
> To: Dave Page
> Cc: Neil Conway; PostgreSQL Hackers
> Subject: Re: [HACKERS] 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
>