Thread: Re: Interactive Documentation - how do you want it towork?
> -----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.
Dave Page wrote: > > 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? Yes, I can see keeping the old comments on old releases, but frankly, if it requires any special effort, it isn't worth the trouble. We are improving this thing so fast I can barely keep up. -- 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
Dave Page wrote: > > > -----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. > -- 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
"Dave Page" <dpage@vale-housing.co.uk> writes:
> 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?
It seems clear to me that the comments *should* be version specific,
if that's at all feasible. When we make a new release then we can
start with zero comments if that seems appropriate --- but as long as
an older set of docs remains on-line, it should have the comments that
were made for it.
regards, tom lane