Re: Interactive Documentation - how do you want it to

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