Re: Interactive Documentation - how do you want it towork?

I looked at that URL, and it is good example of what _not_ to do with
interactive docs, IMHO. The manual page is _very_ short, and shows no
examples. The comments have various examples/cases, with corrections
later to earlier postings. I would think this is not what we want. We
want a longer manual page, with _correct_ examples that show typical
usage.

I know folks like those comments, but isn't it showing cases where the
curt documentation just doesn't cut it?

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

Dave Page wrote:
> 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(at)candle(dot)pha(dot)pa(dot)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(at)samurai(dot)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(at)postgresql(dot)org)
> > >
> >
> > --
> > Bruce Momjian | http://candle.pha.pa.us
> > pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 359-1001
> > + If your life is a hard drive, | 13 Roberts Road
> > + Christ can be your backup. | Newtown Square,
> > Pennsylvania 19073
> >
>

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