Thread: Interactive Documentation - how do you want it to work?

Interactive Documentation - how do you want it to work?

From
"Dave Page"
Date:
As you may have noticed we have recently revamped the Interactive
Documentation on the website (http://www.postgresql.org/docs). This has
raised a couple of questions about how the idocs should work, so I'd
like to get some votes on the following 2 issues:

1) How should comments be linked to document sets?:
- Each comment attaches only to the page name & version of the page to
which it was submitted.
- 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.

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?
- Yes
- No

Thanks, Dave.


Re: Interactive Documentation - how do you want it to

From
Neil Conway
Date:
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...

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

Cheers,

Neil
-- 
Neil Conway <neilc@samurai.com> || PGP Key ID: DB3C29FC





Re: Interactive Documentation - how do you want it to

From
Gavin Sherry
Date:
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



Re: Interactive Documentation - how do you want it to

From
Rod Taylor
Date:
> While we're talking about modifications to idocs, why not have a rating
> system for the usefulness of a comment.

Comment ratings could be useful if the rating is tied to a doc version.
A very useful 7.1 comment may be a little antiquated for 7.3.  This
would solve almost all of the issues if comments are ordered by rating.

--
Rod Taylor <rbt@rbt.ca>

PGP Key: http://www.rbt.ca/rbtpub.asc

Re: Interactive Documentation - how do you want it to work?

From
Bruce Momjian
Date:
Yes, please delete the old comments.  We want to merge as many in as we
can, and remove the rest.

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

Dave Page wrote:
> 
> As you may have noticed we have recently revamped the Interactive
> Documentation on the website (http://www.postgresql.org/docs). This has
> raised a couple of questions about how the idocs should work, so I'd
> like to get some votes on the following 2 issues:
> 
> 1) How should comments be linked to document sets?:
> 
>  - Each comment attaches only to the page name & version of the page to
> which it was submitted.
> 
>  - 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.
> 
> 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?
> 
>  - Yes
> 
>  - No
> 
> Thanks, Dave.
> 
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Don't 'kill -9' the postmaster
> 

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

From
Bruce Momjian
Date:
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@postgresql.org
> 

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