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

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@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
> > 
> 

--  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,
Pennsylvania19073