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

Dave Page wrote:
>
> > -----Original Message-----
> > From: Bruce Momjian [mailto:pgman(at)candle(dot)pha(dot)pa(dot)us]
> > Sent: 03 February 2003 11:40
> > To: Dave Page
> > Cc: Neil Conway; PostgreSQL Hackers
> > Subject: Re: [HACKERS] 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?
>
> OK point taken. What about the issue that the comments get merged into
> later docs, which is often not helpful if someone is searching the older
> docset (because they are using the older version)?
>
> Perhaps we should then prune the garbage out of the old version, and
> make the comments version specific so that we start afresh with the new
> docs, but leave the useful comments against the older versions?
>
> Regards, Dave.
>

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