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

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