Обсуждение: Re: Interactive Documentation - how do you want it towork?

Поиск
Список
Период
Сортировка

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

От
"Dave Page"
Дата:
> -----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.


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

От
Bruce Momjian
Дата:
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
 


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

От
Bruce Momjian
Дата:
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
 


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

От
Tom Lane
Дата:
"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