> -----Original Message-----
> From: Bruce Momjian [mailto:pgman@candle.pha.pa.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.