Re: Doc comments on unsupported versions

From: Magnus Hagander <magnus(at)hagander(dot)net>
To: Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com>
Cc: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, "Jonathan S(dot) Katz" <jkatz(at)postgresql(dot)org>, Daniel Gustafsson <daniel(at)yesql(dot)se>, PostgreSQL www <pgsql-www(at)postgresql(dot)org>
Subject: Re: Doc comments on unsupported versions
Date: 2018-05-03 17:38:43
Message-ID: CABUevEwNnJa93aw5JYc2feWQCX+w=Jg-qC8515XqT0vVTBTp7g@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-www

On Thu, May 3, 2018 at 4:08 PM, Peter Eisentraut <
peter(dot)eisentraut(at)2ndquadrant(dot)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

In response to

Responses

Browse pgsql-www by date

  From Date Subject
Next Message Daniel Gustafsson 2018-05-03 17:41:35 Re: Doc comments on unsupported versions
Previous Message Peter Eisentraut 2018-05-03 14:08:58 Re: Doc comments on unsupported versions