Обсуждение: Doc comments on unsupported versions
The doc comment form is linked from all doc pages, and while most submissions are from supported versions there are sometimes reports coming in from old versions. Since fixes aren’t applied to unsupported versions, and many reports against old version have been fixed already, only allowing comments on supported versions seems reasonable. The attached (untested) patch implements a proposal for this. Is something like this of interest, or are we putting enough value on the comments on unsupported versions that we want to keep them? cheers ./daniel
Вложения
On Fri, Feb 16, 2018 at 10:02 PM, Daniel Gustafsson <daniel@yesql.se> wrote:
The doc comment form is linked from all doc pages, and while most submissions
are from supported versions there are sometimes reports coming in from old
versions. Since fixes aren’t applied to unsupported versions, and many reports
against old version have been fixed already, only allowing comments on
supported versions seems reasonable. The attached (untested) patch implements
a proposal for this.
Is something like this of interest, or are we putting enough value on the
comments on unsupported versions that we want to keep them?
I think yes, let's drop it for unsupported versions. The more we can make it clear to people that they're unsupported, the better.
On 2/16/18 16:02, Daniel Gustafsson wrote: > The doc comment form is linked from all doc pages, and while most submissions > are from supported versions there are sometimes reports coming in from old > versions. Has anything changed about this recently? It seems like we are getting a lot more comments from old versions now. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Feb 17, 2018, at 1:35 PM, Magnus Hagander <magnus@hagander.net> wrote:On Fri, Feb 16, 2018 at 10:02 PM, Daniel Gustafsson <daniel@yesql.se> wrote:The doc comment form is linked from all doc pages, and while most submissions
are from supported versions there are sometimes reports coming in from old
versions. Since fixes aren’t applied to unsupported versions, and many reports
against old version have been fixed already, only allowing comments on
supported versions seems reasonable. The attached (untested) patch implements
a proposal for this.
Is something like this of interest, or are we putting enough value on the
comments on unsupported versions that we want to keep them?I think yes, let's drop it for unsupported versions. The more we can make it clear to people that they're unsupported, the better.
Just to argue the other side, just because the versions are unsupported
does not mean that people are not using those versions and at scale.
If there is something that is erroneous in the documentation, it would
not hurt to fix it, and there is a chance it is incorrect in a supported version.
With that said, it is understandably additional administrative overhead on
our end and it just limiting doc comments to supported versions (and possibly
devel?) would limit our focus on just keeping the supported docs up to date.
I’m fine with dropping the support for this on unsupported versions. If
there is something seriously incorrect with those documents that require updating,
there are other ways to reach out.
Jonathan
> On Feb 18, 2018, at 5:42 PM, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote: > > On 2/16/18 16:02, Daniel Gustafsson wrote: >> The doc comment form is linked from all doc pages, and while most submissions >> are from supported versions there are sometimes reports coming in from old >> versions. > > Has anything changed about this recently? It seems like we are getting > a lot more comments from old versions now. I’ve noticed more document comments too. I don’t have the numbers, butIt may just mean that we have more people reading the docs :-) Jonathan
On Sunday, February 18, 2018, Jonathan S. Katz <jkatz@postgresql.org> wrote:
> On Feb 18, 2018, at 5:42 PM, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>
> On 2/16/18 16:02, Daniel Gustafsson wrote:
>> The doc comment form is linked from all doc pages, and while most submissions
>> are from supported versions there are sometimes reports coming in from old
>> versions.
>
> Has anything changed about this recently? It seems like we are getting
> a lot more comments from old versions now.
I’ve noticed more document comments too. I don’t have the numbers, butIt
may just mean that we have more people reading the docs :-)
Staying on the tangent, I concur but it also seems like some (maybe half...) that I see are responses where I never saw the original hit my inbox.
David J.
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> On Feb 17, 2018, at 1:35 PM, Magnus Hagander <magnus@hagander.net> wrote:
>> I think yes, let's drop it for unsupported versions. The more we can make it clear to people that they're
unsupported,the better.
> Just to argue the other side, just because the versions are unsupported
> does not mean that people are not using those versions and at scale.
> If there is something that is erroneous in the documentation, it would
> not hurt to fix it, and there is a chance it is incorrect in a supported version.
I can't see that we'd expend the effort to fix documentation in
de-supported versions. But certainly, if someone were to point out an
error that also exists in supported versions, we'd wish to fix it in the
supported versions. Is there a way, rather than just blocking comments on
the old versions, to provide a message to the effect of "please comment
on version x.y or newer, if the issue still exists there"?
regards, tom lane
On Sun, Feb 18, 2018 at 11:42 PM, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
On 2/16/18 16:02, Daniel Gustafsson wrote:
> The doc comment form is linked from all doc pages, and while most submissions
> are from supported versions there are sometimes reports coming in from old
> versions.
Has anything changed about this recently? It seems like we are getting
a lot more comments from old versions now.
In December the sending address of comments was changed to be a noreply address, which probably means a smaller amount of the doc comments ended up in spam filters. That may be part of it, but of course it doesn't make a difference between supported and unsupported versions.
The bigger change was in May 2016 when we switched from keeping the comments on the website to actually generating emails. But I don't think that can be called recently.
On Mon, Feb 19, 2018 at 6:09 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> On Feb 17, 2018, at 1:35 PM, Magnus Hagander <magnus@hagander.net> wrote:
>> I think yes, let's drop it for unsupported versions. The more we can make it clear to people that they're unsupported, the better.
> Just to argue the other side, just because the versions are unsupported
> does not mean that people are not using those versions and at scale.
> If there is something that is erroneous in the documentation, it would
> not hurt to fix it, and there is a chance it is incorrect in a supported version.
I can't see that we'd expend the effort to fix documentation in
de-supported versions. But certainly, if someone were to point out an
error that also exists in supported versions, we'd wish to fix it in the
supported versions. Is there a way, rather than just blocking comments on
the old versions, to provide a message to the effect of "please comment
on version x.y or newer, if the issue still exists there"?
That is pretty much what Daniels patch does (except it writes it too many times, but the general idea). It has:
+ If you see anything in the documentation that is not correct, does not match
+ your experience with the particular feature or requires further clarification,
+ please check if this has been fixed in the
+ <a href="/docs/current/static/{{page.file}}/">current version</a> of the documentation. If
+ not, please report a documentation issue using the form on that page.
(text of course easily tweakable)
On 2/19/18 09:02, Magnus Hagander wrote:
> I can't see that we'd expend the effort to fix documentation in
> de-supported versions. But certainly, if someone were to point out an
> error that also exists in supported versions, we'd wish to fix it in the
> supported versions. Is there a way, rather than just blocking
> comments on
> the old versions, to provide a message to the effect of "please comment
> on version x.y or newer, if the issue still exists there"?
>
>
> That is pretty much what Daniels patch does (except it writes it too
> many times, but the general idea). It has:
>
> + If you see anything in the documentation that is not
> correct, does not match
> + your experience with the particular feature or requires
> further clarification,
> + please check if this has been fixed in the
> + <a href="/docs/current/static/{{page.file}}/">current
> version</a> of the documentation. If
> + not, please report a documentation issue using the form
> on that page.
>
> (text of course easily tweakable)
Could we please do something about this? It's getting tiresome. Nobody
reads those instructions.
- Disable the link for submitting documentation comments on EOL versions.
- Enforce a minimum number of characters in comments (hello Stack Overflow).
I would even go so far as
- Remove EOL documentation for search engine results.
- Display them in faint grey text color or otherwise make them annoying
to read.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Thu, May 3, 2018 at 4:08 PM, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
On 2/19/18 09:02, Magnus Hagander wrote:
> I can't see that we'd expend the effort to fix documentation in
> de-supported versions. But certainly, if someone were to point out an
> error that also exists in supported versions, we'd wish to fix it in the
> supported versions. Is there a way, rather than just blocking
> comments on
> the old versions, to provide a message to the effect of "please comment
> on version x.y or newer, if the issue still exists there"?
>
>
> That is pretty much what Daniels patch does (except it writes it too
> many times, but the general idea). It has:
>
> + If you see anything in the documentation that is not
> correct, does not match
> + your experience with the particular feature or requires
> further clarification,
> + please check if this has been fixed in the
> + <a href="/docs/current/static/{{page.file}}/">current
> version</a> of the documentation. If
> + not, please report a documentation issue using the form
> on that page.
>
> (text of course easily tweakable)
Could we please do something about this? It's getting tiresome. Nobody
reads those instructions.
It is definitely getting tiresome. I'm not sure why moderators keep *approving* all of these things though -- they're all being put in the moderation queue specifically to make sure only reasonable ones are approved, but it seems some moderators keep approving all of them....
- Disable the link for submitting documentation comments on EOL versions.
I actually thought we had done that, but it seems not. That should be an easy enough fix.
- Enforce a minimum number of characters in comments (hello Stack Overflow).
Do you have a suggested number? :)
I would even go so far as
- Remove EOL documentation for search engine results.
We do include them, but we drop their priority to the lowest possible one. Supposedly that should mean you can only get to them if you explicitly choose which version to include, but it appears search engines really don't give a shit about that.
We have previously said we don't want to remove them completely, because that makes it impossible to search for historical data. But we've also said that maybe we have to give up, because search engines don't even let us de-prioritize our own pages :(
- Display them in faint grey text color or otherwise make them annoying
to read.
Unfortunately, the <blink> tag has been removed from browsers..
//Magnus
> On 03 May 2018, at 19:38, Magnus Hagander <magnus@hagander.net> wrote: > On Thu, May 3, 2018 at 4:08 PM, Peter Eisentraut <peter.eisentraut@2ndquadrant.com <mailto:peter.eisentraut@2ndquadrant.com>>wrote: > - Disable the link for submitting documentation comments on EOL versions. > > I actually thought we had done that, but it seems not. That should be an easy enough fix. I was going to, but put all the www related patches on hold until the new site was launched.. and I’ve been crazy busy since when that happened so haven’t had time to revisit (yet). cheers ./daniel
Magnus Hagander wrote: > It is definitely getting tiresome. I'm not sure why moderators keep > *approving* all of these things though -- they're all being put in the > moderation queue specifically to make sure only reasonable ones are > approved, but it seems some moderators keep approving all of them.... I think it's rude to reject a mailing list message on grounds such as comments being submitted to an old version. Also, if the comment applies to new versions, then the moderator is at fault, and there is no trail or mechanism to put the comment back. In other words, determining the value of the comment is on the moderator's head. I'd rather have the moderators approve the comments, and have the list readership determine that the comment is of no value publicly (that way, if someone else disagrees, they can challenge it on-list.) > > - Disable the link for submitting documentation comments on EOL versions. > > I actually thought we had done that, but it seems not. That should be an > easy enough fix. Sounds good to me. > > - Display them in faint grey text color or otherwise make them annoying > > to read. > > Unfortunately, the <blink> tag has been removed from browsers.. When visiting a Facebook page (without logged in to an account), it keeps pestering you to open your own account. I'm fortunate I don't visit pages often, because it's *really* annoying. Something similar could be applied here, perhaps ... I hope facebook doesn't have a patent on obnoxious layers obscuring the bottom half of the page when not logged in. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Thu, May 3, 2018 at 8:11 PM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
Magnus Hagander wrote:
> It is definitely getting tiresome. I'm not sure why moderators keep
> *approving* all of these things though -- they're all being put in the
> moderation queue specifically to make sure only reasonable ones are
> approved, but it seems some moderators keep approving all of them....
I think it's rude to reject a mailing list message on grounds such as
comments being submitted to an old version. Also, if the comment
applies to new versions, then the moderator is at fault, and there is no
trail or mechanism to put the comment back. In other words, determining
the value of the comment is on the moderator's head. I'd rather have
the moderators approve the comments, and have the list readership
determine that the comment is of no value publicly (that way, if someone
else disagrees, they can challenge it on-list.)
That I agree with, if that's the reason. But there's plenty that have been more or less content-less that have been approved, and I don't think those should've been.
I mean:
or even:
> > - Disable the link for submitting documentation comments on EOL versions.
>
> I actually thought we had done that, but it seems not. That should be an
> easy enough fix.
Sounds good to me.
> > - Display them in faint grey text color or otherwise make them annoying
> > to read.
>
> Unfortunately, the <blink> tag has been removed from browsers..
When visiting a Facebook page (without logged in to an account), it
keeps pestering you to open your own account. I'm fortunate I don't
visit pages often, because it's *really* annoying. Something similar
could be applied here, perhaps ... I hope facebook doesn't have a
patent on obnoxious layers obscuring the bottom half of the page when
not logged in.
Those pages also completely don't work at all without javascript. I definitely don't want to go *there*.
Magnus Hagander wrote: > Thu, May 3, 2018 at 8:11 PM, Alvaro Herrera <alvherre@2ndquadrant.com> > wrote: > > > Magnus Hagander wrote: > That I agree with, if that's the reason. But there's plenty that have been > more or less content-less that have been approved, and I don't think those > should've been. > > I mean: > https://www.postgresql.org/message-id/152273272513.1433.16677492851065826081%40wrigleys.postgresql.org > or even: > https://www.postgresql.org/message-id/152524500200.31689.10330412450106010735%40wrigleys.postgresql.org Hmm, agreed. I don't know if it was I that approved these (very likely the second one), but I'll be more careful and reject bad posts more aggressively too, which will probably help. > > > Unfortunately, the <blink> tag has been removed from browsers.. > > > > When visiting a Facebook page (without logged in to an account), it > > keeps pestering you to open your own account. I'm fortunate I don't > > visit pages often, because it's *really* annoying. Something similar > > could be applied here, perhaps ... I hope facebook doesn't have a > > patent on obnoxious layers obscuring the bottom half of the page when > > not logged in. > > Those pages also completely don't work at all without javascript. I > definitely don't want to go *there*. Well, it's probably easy to work out a mechanism by which the page behaves normally when javascript is disabled, and shows the annoying popup if javascript is enabled. Anyway, this is probably moot if comments are disabled for old versions. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Thu, May 3, 2018 at 9:10 PM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
Magnus Hagander wrote:
> Thu, May 3, 2018 at 8:11 PM, Alvaro Herrera <alvherre@2ndquadrant.com>
> wrote:
>
> > Magnus Hagander wrote:
> That I agree with, if that's the reason. But there's plenty that have been
> more or less content-less that have been approved, and I don't think those
> should've been.
>
> I mean:
> https://www.postgresql.org/message-id/152273272513.1433. 16677492851065826081% 40wrigleys.postgresql.org
> or even:
> https://www.postgresql.org/message-id/152524500200.31689. 10330412450106010735% 40wrigleys.postgresql.org
Hmm, agreed. I don't know if it was I that approved these (very likely
the second one), but I'll be more careful and reject bad posts more
aggressively too, which will probably help.
FWIW, and if that wasn't clear, I wasn't trying to "point fingers". I don't care who approved them (I don't *think* it was me, but sometimes things go a bit too quickly -- as we know from esperience with me and others accidentally moderating the Spanish list once). But it would be good if all moderators are a bit more careful about it.
> > > Unfortunately, the <blink> tag has been removed from browsers..
> >
> > When visiting a Facebook page (without logged in to an account), it
> > keeps pestering you to open your own account. I'm fortunate I don't
> > visit pages often, because it's *really* annoying. Something similar
> > could be applied here, perhaps ... I hope facebook doesn't have a
> > patent on obnoxious layers obscuring the bottom half of the page when
> > not logged in.
>
> Those pages also completely don't work at all without javascript. I
> definitely don't want to go *there*.
Well, it's probably easy to work out a mechanism by which the page
behaves normally when javascript is disabled, and shows the annoying
popup if javascript is enabled. Anyway, this is probably moot if
comments are disabled for old versions.
Yeah, this has been done already.
On Thu, May 03, 2018 at 07:38:43PM +0200, Magnus Hagander wrote: > On Thu, May 3, 2018 at 4:08 PM, Peter Eisentraut < > peter.eisentraut@2ndquadrant.com> wrote: > > - Disable the link for submitting documentation comments on EOL versions. > > I actually thought we had done that, but it seems not. That should be an > easy enough fix. Excellent plan! > - Enforce a minimum number of characters in comments (hello Stack Overflow). > > Do you have a suggested number? :) 5000 would cut down on the silliness pretty completely. 250 would do the same, but be less obviously obnoxious. > > I would even go so far as > > > > - Remove EOL documentation for search engine results. > > We do include them, but we drop their priority to the lowest possible one. > Supposedly that should mean you can only get to them if you explicitly > choose which version to include, but it appears search engines really don't > give a shit about that. > > We have previously said we don't want to remove them completely, because > that makes it impossible to search for historical data. But we've also said > that maybe we have to give up, because search engines don't even let us > de-prioritize our own pages :( I think that by the time someone is searching for things PostgreSQL 8.2, that's specialty enough a request that they should come to postgresql.org and do it rather than relying on someone else's search engine. > > - Display them in faint grey text color or otherwise make them annoying > > to read. > > Unfortunately, the <blink> tag has been removed from browsers.. Fortunately, there are more modern ways to be super annoying. For example: https://codepen.io/anasandoval90/pen/jPXxaR Best, David. -- David Fetter <david(at)fetter(dot)org> http://fetter.org/ Phone: +1 415 235 3778 Remember to vote! Consider donating to Postgres: http://www.postgresql.org/about/donate
On 8 May 2018 at 22:45, David Fetter <david@fetter.org> wrote: > On Thu, May 03, 2018 at 07:38:43PM +0200, Magnus Hagander wrote: >> On Thu, May 3, 2018 at 4:08 PM, Peter Eisentraut < >> peter.eisentraut@2ndquadrant.com> wrote: >> >> - Disable the link for submitting documentation comments on EOL versions. >> >> I actually thought we had done that, but it seems not. That should be an >> easy enough fix. > > Excellent plan! > >> - Enforce a minimum number of characters in comments (hello Stack Overflow). >> >> Do you have a suggested number? :) > > 5000 would cut down on the silliness pretty completely. 250 would do > the same, but be less obviously obnoxious. Counter-argument: "Typo: bluh should be blah" Do we want to make people spam filer into it? Also, many of the really annoying comments are long questions that are completely inappropriate for the docs comments form anyway. People who just refuse to recognise that this isn't a discussion forum. Personally I think a prominent link to the mailing list and Stack Overflow would be good. -- Craig Ringer http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services
On 09/05/18 01:48, Craig Ringer wrote: > Personally I think a prominent link to [...] Stack > Overflow would be good. Let's not and say we did. -- Vik Fearing +33 6 46 75 15 36 http://2ndQuadrant.fr PostgreSQL : Expertise, Formation et Support