Thread: Interactive Doc Comments - Their Future?
Hi Everyone, We have a section on our website for "interactive" documentation, where people can submit their comments on the documentation,and a moderator will go and approve them. Somehow I've become the de facto moderator, which I have no problemwith. However, I have noticed an interesting pattern with the doc comments that are submitted - they all tend tofall into a few categories: 1. Document spelling / indexing corrections2. Feature Requests3. Requests for clarification4. Advice for the reader5. Statementsthat are just plain wrong The only guidelines we have for submitting interactive docs are as such: "Please use this form to add your own comments regarding your experience with particular features of PostgreSQL, clarificationsof the documentation, or hints for other users. Please note, this is not a support forum, and your IP addresswill be logged. If you have a question or need help, please see the faq, try a mailing list, or join us on IRC. Notethat submissions containing URLs or other keywords commonly found in 'spam' comments may be silently discarded. Pleasecontact the webmaster if you think this is happening to you in error." Currently I try to handle these scenarios as such: #1, sometimes #3 - relay to someone working on docs#2, #5 - reject#4 - approve if it seems relevant, otherwise reject So this begs a few questions: * What are the goals for having the interactive docs around?* Are they actually useful? *Is it something we wish to maintainon the website?* If we do remove them, do we want to have better guidance on the static docs on where to submit corrections/ feature requests / etc? My personal thoughts from reading what is submitted is that the doc comments are not that useful and should be removed, butwe should be able to make it easy for people to submit thoughts to -docs or other avenues to get submissions in, particularlywhen they are on a particular document page. But of course, I think this would make for a good discussion :-) So - what, if anything, should we do with the interactivedocs? Best, Jonathan
On Wed, Mar 5, 2014 at 3:33 AM, Jonathan S. Katz <jonathan.katz@excoventures.com> wrote: > Hi Everyone, > > We have a section on our website for "interactive" documentation, where people can submit their comments on the documentation,and a moderator will go and approve them. Somehow I've become the de facto moderator, which I have no problemwith. However, I have noticed an interesting pattern with the doc comments that are submitted - they all tend tofall into a few categories: > > 1. Document spelling / indexing corrections > 2. Feature Requests > 3. Requests for clarification > 4. Advice for the reader > 5. Statements that are just plain wrong > > The only guidelines we have for submitting interactive docs are as such: > > "Please use this form to add your own comments regarding your experience with particular features of PostgreSQL,clarifications of the documentation, or hints for other users. Please note, this is not a support forum, and yourIP address will be logged. If you have a question or need help, please see the faq, try a mailing list, or join us onIRC. Note that submissions containing URLs or other keywords commonly found in 'spam' comments may be silently discarded.Please contact the webmaster if you think this is happening to you in error." > > Currently I try to handle these scenarios as such: > > #1, sometimes #3 - relay to someone working on docs > #2, #5 - reject > #4 - approve if it seems relevant, otherwise reject > > So this begs a few questions: > > * What are the goals for having the interactive docs around? > * Are they actually useful? > *Is it something we wish to maintain on the website? > * If we do remove them, do we want to have better guidance on the static docs on where to submit corrections /feature requests / etc? > > My personal thoughts from reading what is submitted is that the doc comments are not that useful and should be removed,but we should be able to make it easy for people to submit thoughts to -docs or other avenues to get submissionsin, particularly when they are on a particular document page. > > But of course, I think this would make for a good discussion :-) So - what, if anything, should we do with the interactivedocs? They were originally inspired by the comment system on the PHP doc website, which if you've ever hacked with PHP you'll probably agree is an invaluable resource - however, that's largely because the PHP docs just aren't great (IMHO, YMMV etc. etc.). Having user submitted code examples and additional explanation is very useful. Our docs are far better however, so naturally the comments are less useful. That said, I have, on odd occasions, found them to be helpful. Personally, I'd vote for keeping them, if you or others are happy to continue with the moderation tasks. -- Dave Page Blog: http://pgsnake.blogspot.com Twitter: @pgsnake EnterpriseDB UK: http://www.enterprisedb.com The Enterprise PostgreSQL Company
On Mar 5, 2014, at 3:43 AM, Dave Page wrote: > On Wed, Mar 5, 2014 at 3:33 AM, Jonathan S. Katz > <jonathan.katz@excoventures.com> wrote: >> Hi Everyone, >> >> We have a section on our website for "interactive" documentation, where people can submit their comments on the documentation,and a moderator will go and approve them. Somehow I've become the de facto moderator, which I have no problemwith. However, I have noticed an interesting pattern with the doc comments that are submitted - they all tend tofall into a few categories: >> >> 1. Document spelling / indexing corrections >> 2. Feature Requests >> 3. Requests for clarification >> 4. Advice for the reader >> 5. Statements that are just plain wrong >> >> The only guidelines we have for submitting interactive docs are as such: >> >> "Please use this form to add your own comments regarding your experience with particular features of PostgreSQL,clarifications of the documentation, or hints for other users. Please note, this is not a support forum, and yourIP address will be logged. If you have a question or need help, please see the faq, try a mailing list, or join us onIRC. Note that submissions containing URLs or other keywords commonly found in 'spam' comments may be silently discarded.Please contact the webmaster if you think this is happening to you in error." >> >> Currently I try to handle these scenarios as such: >> >> #1, sometimes #3 - relay to someone working on docs >> #2, #5 - reject >> #4 - approve if it seems relevant, otherwise reject >> >> So this begs a few questions: >> >> * What are the goals for having the interactive docs around? >> * Are they actually useful? >> *Is it something we wish to maintain on the website? >> * If we do remove them, do we want to have better guidance on the static docs on where to submit corrections /feature requests / etc? >> >> My personal thoughts from reading what is submitted is that the doc comments are not that useful and should be removed,but we should be able to make it easy for people to submit thoughts to -docs or other avenues to get submissionsin, particularly when they are on a particular document page. >> >> But of course, I think this would make for a good discussion :-) So - what, if anything, should we do with the interactivedocs? > > They were originally inspired by the comment system on the PHP doc > website, which if you've ever hacked with PHP you'll probably agree is > an invaluable resource - however, that's largely because the PHP docs > just aren't great (IMHO, YMMV etc. etc.). I kind of figured they were inspired by the PHP docs, and yes, I totally agree that the PHP comments were definitely a welcomesupplement to the documentation, particularly PHP4 (IMHO, YMMV, etc. etc., to borrow your phrase) > Having user submitted code > examples and additional explanation is very useful. Our docs are far > better however, so naturally the comments are less useful. That said, > I have, on odd occasions, found them to be helpful. Personally, I'd > vote for keeping them, if you or others are happy to continue with the > moderation tasks. I am sure there are past examples that are helpful, but the issue is what we are getting with the current submissions, alot of which are requests for clarification or additions more suited for -general, #postgresql or even -docs. With that said, does anyone involved with -docs pay attention to new comments? I'm not sure if an alert is sent over there. If it is, it makes the submissions much more useful and allows for a level of interactivity. Jonathan
On Wed, Mar 5, 2014 at 10:36:02AM -0500, Jonathan Katz wrote: > With that said, does anyone involved with -docs pay attention to new > comments? I'm not sure if an alert is sent over there. If it is, > it makes the submissions much more useful and allows for a level of > interactivity. I believe Tom Lane goes over the comments before every major release and merges useful suggestions into our docs. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + Everyone has their own god. +
Bruce Momjian <bruce@momjian.us> writes:
> On Wed, Mar 5, 2014 at 10:36:02AM -0500, Jonathan Katz wrote:
>> With that said, does anyone involved with -docs pay attention to new
>> comments? I'm not sure if an alert is sent over there. If it is,
>> it makes the submissions much more useful and allows for a level of
>> interactivity.
> I believe Tom Lane goes over the comments before every major release and
> merges useful suggestions into our docs.
Uh, no. That would possibly be a useful thing to do, but I don't do it
--- I don't even have a way to examine the existing comments, short of
manually visiting every one of the HTML pages.
regards, tom lane
On Mar 5, 2014, at 10:43 AM, Tom Lane wrote: > Bruce Momjian <bruce@momjian.us> writes: >> On Wed, Mar 5, 2014 at 10:36:02AM -0500, Jonathan Katz wrote: >>> With that said, does anyone involved with -docs pay attention to new >>> comments? I'm not sure if an alert is sent over there. If it is, >>> it makes the submissions much more useful and allows for a level of >>> interactivity. > >> I believe Tom Lane goes over the comments before every major release and >> merges useful suggestions into our docs. > > Uh, no. That would possibly be a useful thing to do, but I don't do it > --- I don't even have a way to examine the existing comments, short of > manually visiting every one of the HTML pages. It's very easy from the www admin page, but you would need access (not sure if you have already?) Jonathan
On Wed, Mar 5, 2014 at 10:43:57AM -0500, Tom Lane wrote: > Bruce Momjian <bruce@momjian.us> writes: > > On Wed, Mar 5, 2014 at 10:36:02AM -0500, Jonathan Katz wrote: > >> With that said, does anyone involved with -docs pay attention to new > >> comments? I'm not sure if an alert is sent over there. If it is, > >> it makes the submissions much more useful and allows for a level of > >> interactivity. > > > I believe Tom Lane goes over the comments before every major release and > > merges useful suggestions into our docs. > > Uh, no. That would possibly be a useful thing to do, but I don't do it > --- I don't even have a way to examine the existing comments, short of > manually visiting every one of the HTML pages. Uh, I see you tried to do it in 2003: http://www.postgresql.org/message-id/20545.1068921919@sss.pgh.pa.us and I see you doing it in 2005: commit 7da8623a562d3f6c25363796ed3df086a4da4594Author: Tom Lane <tgl@sss.pgh.pa.us>Date: Sun Jan 9 18:58:10 2005 +0000 Last batch of updates in response to 7.4 interactive docs comments. I assumed you were still doing it, but I don't see anything post-2005, so I am concerned we have not been doing it recently. Can someone confirm this and perhaps do it for post-2005? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + Everyone has their own god. +
On Wed, Mar 5, 2014 at 4:33 AM, Jonathan S. Katz <jonathan.katz@excoventures.com> wrote:
Hi Everyone,
We have a section on our website for "interactive" documentation, where people can submit their comments on the documentation, and a moderator will go and approve them. Somehow I've become the de facto moderator, which I have no problem with. However, I have noticed an interesting pattern with the doc comments that are submitted - they all tend to fall into a few categories:
1. Document spelling / indexing corrections
2. Feature Requests
3. Requests for clarification
4. Advice for the reader
5. Statements that are just plain wrong
In my experience, a lot of othem fall under either #5, or under the category of repeating something that's already on the page.
The only guidelines we have for submitting interactive docs are as such:
"Please use this form to add your own comments regarding your experience with particular features of PostgreSQL, clarifications of the documentation, or hints for other users. Please note, this is not a support forum, and your IP address will be logged. If you have a question or need help, please see the faq, try a mailing list, or join us on IRC. Note that submissions containing URLs or other keywords commonly found in 'spam' comments may be silently discarded. Please contact the webmaster if you think this is happening to you in error."
Currently I try to handle these scenarios as such:
#1, sometimes #3 - relay to someone working on docs
#2, #5 - reject
#4 - approve if it seems relevant, otherwise reject
So this begs a few questions:
* What are the goals for having the interactive docs around?
* Are they actually useful?
*Is it something we wish to maintain on the website?
* If we do remove them, do we want to have better guidance on the static docs on where to submit corrections / feature requests / etc?
My personal thoughts from reading what is submitted is that the doc comments are not that useful and should be removed, but we should be able to make it easy for people to submit thoughts to -docs or other avenues to get submissions in, particularly when they are on a particular document page.
But of course, I think this would make for a good discussion :-) So - what, if anything, should we do with the interactive docs?
They're not particularly interactive today. They're a one way submission, and then a moderator.
Perhaps what we could do is replace them with something that works like the bug report form. So instead of submitting a comment into a static space, they turn into an email to the -docs list, which can then get discussion around it and eventually turn it into a modifications for the actual docs?
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
Magnus Hagander wrote: > Perhaps what we could do is replace them with something that works like the > bug report form. So instead of submitting a comment into a static space, > they turn into an email to the -docs list, which can then get discussion > around it and eventually turn it into a modifications for the actual docs? No objection, but can we please get an extra moderator for pgsql-docs? -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services
On 3/5/14, 2:17 PM, Magnus Hagander wrote: > Perhaps what we could do is replace them with something that works like > the bug report form. So instead of submitting a comment into a static > space, they turn into an email to the -docs list, which can then get > discussion around it and eventually turn it into a modifications for the > actual docs? That seems most useful to me.
On Mar 5, 2014, at 3:41 PM, Peter Eisentraut wrote: > On 3/5/14, 2:17 PM, Magnus Hagander wrote: >> Perhaps what we could do is replace them with something that works like >> the bug report form. So instead of submitting a comment into a static >> space, they turn into an email to the -docs list, which can then get >> discussion around it and eventually turn it into a modifications for the >> actual docs? > > That seems most useful to me. Yes, because ultimately, with a lot of doc comments that come in, this is what I would do anyway (and in fairness, I havequeued up a bunch to send over) Jonathan
Jonathan S. Katz wrote: > On Mar 5, 2014, at 3:41 PM, Peter Eisentraut wrote: > > > On 3/5/14, 2:17 PM, Magnus Hagander wrote: > >> Perhaps what we could do is replace them with something that works like > >> the bug report form. So instead of submitting a comment into a static > >> space, they turn into an email to the -docs list, which can then get > >> discussion around it and eventually turn it into a modifications for the > >> actual docs? > > > > That seems most useful to me. > > Yes, because ultimately, with a lot of doc comments that come in, this is what I would do anyway (and in fairness, I havequeued up a bunch to send over) So in short the "interactive" docs would go away (i.e. no comments are displayed), and the form in the docs/interactive/ pages would submit a comment to pgsql-docs, so that hopefully we merge the useful ones into the main text. The docs/interactive/ URLs would redirect to the static pages (or perhaps serve the same contents without redirecting?) Is that it? -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services
On Thu, Mar 6, 2014 at 4:16 PM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
So in short the "interactive" docs would go away (i.e. no comments areJonathan S. Katz wrote:
> On Mar 5, 2014, at 3:41 PM, Peter Eisentraut wrote:
>
> > On 3/5/14, 2:17 PM, Magnus Hagander wrote:
> >> Perhaps what we could do is replace them with something that works like
> >> the bug report form. So instead of submitting a comment into a static
> >> space, they turn into an email to the -docs list, which can then get
> >> discussion around it and eventually turn it into a modifications for the
> >> actual docs?
> >
> > That seems most useful to me.
>
> Yes, because ultimately, with a lot of doc comments that come in, this is what I would do anyway (and in fairness, I have queued up a bunch to send over)
displayed), and the form in the docs/interactive/ pages would submit a
comment to pgsql-docs, so that hopefully we merge the useful ones into
the main text. The docs/interactive/ URLs would redirect to the static
pages (or perhaps serve the same contents without redirecting?)
Is that it?
Yes, that sums up my suggestion well.
I think the best is to redirect to static and actually add the form to the bottom of the static pages as well. There's no need to keep them separate if all we have is the feedback box, is there? (We could even use some javascript magic to hide it behind a click).
We'd want the redirects to happen rather than serve up the same content, for SEO reasons.
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Thu, Mar 6, 2014 at 12:16:39PM -0300, Alvaro Herrera wrote: > Jonathan S. Katz wrote: > > On Mar 5, 2014, at 3:41 PM, Peter Eisentraut wrote: > > > > > On 3/5/14, 2:17 PM, Magnus Hagander wrote: > > >> Perhaps what we could do is replace them with something that works like > > >> the bug report form. So instead of submitting a comment into a static > > >> space, they turn into an email to the -docs list, which can then get > > >> discussion around it and eventually turn it into a modifications for the > > >> actual docs? > > > > > > That seems most useful to me. > > > > Yes, because ultimately, with a lot of doc comments that come in, this is what I would do anyway (and in fairness, Ihave queued up a bunch to send over) > > So in short the "interactive" docs would go away (i.e. no comments are > displayed), and the form in the docs/interactive/ pages would submit a > comment to pgsql-docs, so that hopefully we merge the useful ones into > the main text. The docs/interactive/ URLs would redirect to the static > pages (or perhaps serve the same contents without redirecting?) Good. I have disliked that users had to choose with/without comments before seeing the docs. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + Everyone has their own god. +
Magnus Hagander wrote: > On Thu, Mar 6, 2014 at 4:16 PM, Alvaro Herrera <alvherre@2ndquadrant.com>wrote: > > So in short the "interactive" docs would go away (i.e. no comments are > > displayed), and the form in the docs/interactive/ pages would submit a > > comment to pgsql-docs, so that hopefully we merge the useful ones into > > the main text. The docs/interactive/ URLs would redirect to the static > > pages (or perhaps serve the same contents without redirecting?) > > Yes, that sums up my suggestion well. So, is anyone going to work on this? I just noticed that there are two dozens of comments pending moderation right now. -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services
On Wed, Jul 30, 2014 at 06:13:31PM -0400, Alvaro Herrera wrote: > Magnus Hagander wrote: > > On Thu, Mar 6, 2014 at 4:16 PM, Alvaro Herrera <alvherre@2ndquadrant.com>wrote: > > > > So in short the "interactive" docs would go away (i.e. no comments are > > > displayed), and the form in the docs/interactive/ pages would submit a > > > comment to pgsql-docs, so that hopefully we merge the useful ones into > > > the main text. The docs/interactive/ URLs would redirect to the static > > > pages (or perhaps serve the same contents without redirecting?) > > > > Yes, that sums up my suggestion well. > > So, is anyone going to work on this? I just noticed that there are two > dozens of comments pending moderation right now. Ten months later, is anyone working on this? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + Everyone has their own god. +
<p dir="ltr"><br /> On May 14, 2015 10:42 PM, "Bruce Momjian" <<a href="mailto:bruce@momjian.us">bruce@momjian.us</a>>wrote:<br /> ><br /> > On Wed, Jul 30, 2014 at 06:13:31PM -0400,Alvaro Herrera wrote:<br /> > > Magnus Hagander wrote:<br /> > > > On Thu, Mar 6, 2014 at 4:16 PM, AlvaroHerrera <<a href="mailto:alvherre@2ndquadrant.com">alvherre@2ndquadrant.com</a>>wrote:<br /> > ><br />> > > > So in short the "interactive" docs would go away (i.e. no comments are<br /> > > > > displayed),and the form in the docs/interactive/ pages would submit a<br /> > > > > comment to pgsql-docs, sothat hopefully we merge the useful ones into<br /> > > > > the main text. The docs/interactive/ URLs wouldredirect to the static<br /> > > > > pages (or perhaps serve the same contents without redirecting?)<br/> > > ><br /> > > > Yes, that sums up my suggestion well.<br /> > ><br /> > >So, is anyone going to work on this? I just noticed that there are two<br /> > > dozens of comments pending moderationright now.<br /> ><br /> > Ten months later, is anyone working on this?<br /> ><p dir="ltr">Certainlyseems like "no". I think it was forgotten, so thanks for the reminder. <p dir="ltr">I know Jonathan startedlooking at it after your reminder, so hopefully we can have something before another ten months pass...<br /><p dir="ltr">/Magnus<br />
On Wed, May 20, 2015 at 11:21 AM, Magnus Hagander <magnus@hagander.net> wrote:
On May 14, 2015 10:42 PM, "Bruce Momjian" <bruce@momjian.us> wrote:
>
> On Wed, Jul 30, 2014 at 06:13:31PM -0400, Alvaro Herrera wrote:
> > Magnus Hagander wrote:
> > > On Thu, Mar 6, 2014 at 4:16 PM, Alvaro Herrera <alvherre@2ndquadrant.com>wrote:
> >
> > > > So in short the "interactive" docs would go away (i.e. no comments are
> > > > displayed), and the form in the docs/interactive/ pages would submit a
> > > > comment to pgsql-docs, so that hopefully we merge the useful ones into
> > > > the main text. The docs/interactive/ URLs would redirect to the static
> > > > pages (or perhaps serve the same contents without redirecting?)
> > >
> > > Yes, that sums up my suggestion well.
> >
> > So, is anyone going to work on this? I just noticed that there are two
> > dozens of comments pending moderation right now.
>
> Ten months later, is anyone working on this?
>Certainly seems like "no". I think it was forgotten, so thanks for the reminder.
I know Jonathan started looking at it after your reminder, so hopefully we can have something before another ten months pass...
Wow, look, only about 2 years later, but this is actually done now.