Re: Interactive Documentation - how do you want it to

Folks, we want organized documentation, not cudos to commentors or
something that is so large that people have to wade through the comments
to see if something is interesting. The focus is the docs, and the
comments are only there to improve the docs. They are there for no
other reason.

---------------------------------------------------------------------------

Gavin Sherry wrote:
> On 2 Feb 2003, Neil Conway wrote:
>
> > On Sun, 2003-02-02 at 15:22, Dave Page wrote:
> > > - Each comment attaches only to the page name, version of the page to
> > > which it was submitted *and* subsequent versions (this is the current
> > > behaviour).
> > >
> > > - Each comment should attach to the page name to which it was submitted
> > > regardless of the version.
> >
> > IMHO either one of these, considering below...
>
> Agreed.
>
> >
> > > 2) Bearing in mind your answer to the previous question, should all the
> > > comments be deleted when useful examples have been merged into the main
> > > documents (remember that the definition of 'useful' may vary), or should
> > > we only remove the 'junk' ones?
> >
> > Once the comment's suggestion has been incorporated and the docs
> > updated, I think it should be removed. Just like in the rest of the
> > documentation, there's no point presenting duplicate content to the
> > user, so we should only keep the idocs comments that are still relevant.
> > The same goes for comments that have no value (e.g. support requests).
>
> I do not think that useful comments should be deleted, even when the
> suggestions there in are incorporated into documentation. Instead, they
> (the user comments) should be marked as being incorporated into
> documentation of release X.Y.Z. I think this is more useful because 1) it
> provides some credit to user who provided the example; and 2) it gives
> readers a user perspective on the problem which they can compare to the
> documentation -- the language of documentation can sometimes be too brief.
>
> While we're talking about modifications to idocs, why not have a rating
> system for the usefulness of a comment.
>
> Also, how about some obfuscation of the email addresses included with user
> comments?
>
> Gavin
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 1: subscribe and unsubscribe commands go to majordomo(at)postgresql(dot)org
>

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