Обсуждение: Interactive Documentation - how do you want it to work?
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.
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
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
> 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
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
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