Обсуждение: A user report of misinterpretation of 'unsupported versions'

I had a report from a user asking how they could VACUUM in the future
under 9.3, when it's no longer supported (which took me aback).  He
referred me to a manual page:

http://www.postgresql.org/docs/current/static/sql-vacuum.html

I realized, then, that the problem is the wordsmithing of:

"This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  Unsupported
versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1 / devel"

An entirely reasonable person would decide that the VACUUM command is
unsupported in any of the itemized versions.

On Thu, Jul 11, 2013 at 1:03 AM, Daniel Farina <daniel@heroku.com> wrote:
> I had a report from a user asking how they could VACUUM in the future
> under 9.3, when it's no longer supported (which took me aback).  He
> referred me to a manual page:
>
> http://www.postgresql.org/docs/current/static/sql-vacuum.html
>
> I realized, then, that the problem is the wordsmithing of:
>
> "This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  Unsupported
> versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1 / devel"
>
> An entirely reasonable person would decide that the VACUUM command is
> unsupported in any of the itemized versions.

Strictly speaking, *everything in 9.3 is unsupported. Because it
hasn't been released yet.

But I can understand the confusion - do you have a suggestion for how
to write it to make it more obvious what the actual problem is?

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

On 7/12/13 6:28 AM, Magnus Hagander wrote:
> "This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  Unsupported
>> versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1 / devel"

"This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  Devel: 9.3 |
EOL: 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1"

Although EOL is very much jargon.

On Fri, Jul 12, 2013 at 3:28 AM, Magnus Hagander <magnus@hagander.net> wrote:
>
> On Thu, Jul 11, 2013 at 1:03 AM, Daniel Farina <daniel@heroku.com> wrote:
> > I had a report from a user asking how they could VACUUM in the future
> > under 9.3, when it's no longer supported (which took me aback).  He
> > referred me to a manual page:
> >
> > http://www.postgresql.org/docs/current/static/sql-vacuum.html
> >
> > I realized, then, that the problem is the wordsmithing of:
> >
> > "This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  Unsupported
> > versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1 / devel"
> >
> > An entirely reasonable person would decide that the VACUUM command is
> > unsupported in any of the itemized versions.
>
> Strictly speaking, *everything in 9.3 is unsupported. Because it
> hasn't been released yet.
>
> But I can understand the confusion - do you have a suggestion for how
> to write it to make it more obvious what the actual problem is?

I don't think I communicated the problem right.  Or maybe I did, but I
can't tell from the response.  So, forgive me for hashing it again in
another way.

The problem is the thinking process goes like this:

I'm sitting on a page about VACUUM, and here's a bit of text itemizing
what versions VACUUM exists in.  But here's a bit of text saying that
VACUUM isn't supported (read to mean: non-existent) in [7.1,8.3] +
9.3.  The thing the user was being led to believe was that VACUUM was
undergoing deprecation.

In other words, he chose to tighter-bind the supported/unsupported to
the topic of the page, rather than the status of the entire release.

Daniel Farina <daniel@heroku.com> writes:
> On Fri, Jul 12, 2013 at 3:28 AM, Magnus Hagander <magnus@hagander.net> wrote:
>> But I can understand the confusion - do you have a suggestion for how
>> to write it to make it more obvious what the actual problem is?

> I don't think I communicated the problem right.

Yeah, you did, but we need a concrete suggestion as to how to improve
the wording.

I wonder if just adding "in" would help:

This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  In unsupported versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3
/7.2 / devel 

Another possibility is to replace "unsupported" with something more
explicit:

This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  Unreleased or obsolete versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 /
7.4/ 7.3 / 7.2 / devel 

            regards, tom lane

-----BEGIN PGP SIGNED MESSAGE-----
Hash: RIPEMD160


> "This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  Unsupported
> versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1 / devel"
>
> An entirely reasonable person would decide that the VACUUM command is
> unsupported in any of the itemized versions.

How about we simply list all versions, without classifying them as
unsupported or not? Not sure how useful our scolding^H^Hinforming
people that 7.4 is old and unsupported is on a page about vacuuming.

- --
Greg Sabino Mullane greg@endpoint.com  greg@turnstep.com
End Point Corporation 610-983-9073
PGP Key: 0x14964AC8 201307122200
http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8
-----BEGIN PGP SIGNATURE-----

iEYEAREDAAYFAlHgtO8ACgkQvJuQZxSWSshI2wCg1Gt3u8LZ312SRqBH6k9mPAwF
hv8AoMShMaEHUta807dkGLO8H3FOjtey
=BDnQ
-----END PGP SIGNATURE-----

On Fri, Jul 12, 2013 at 5:44 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Daniel Farina <daniel@heroku.com> writes:
>> On Fri, Jul 12, 2013 at 3:28 AM, Magnus Hagander <magnus@hagander.net> wrote:
>>> But I can understand the confusion - do you have a suggestion for how
>>> to write it to make it more obvious what the actual problem is?
>
>> I don't think I communicated the problem right.
>
> Yeah, you did, but we need a concrete suggestion as to how to improve
> the wording.

Yeah. Well, I wanted to make sure I got my point across right before
doing any suggestions.

> I wonder if just adding "in" would help:
>
> This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  In unsupported versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 /
7.3/ 7.2 / devel 

That seems like a good suggestion to me.  Granted, this kind of user
complaint is pretty rare to catch articulated, so it's hard to do much
other than intuition...but I like it.

On Sat, Jul 13, 2013 at 3:12 AM, Daniel Farina <daniel@heroku.com> wrote:
> On Fri, Jul 12, 2013 at 5:44 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Daniel Farina <daniel@heroku.com> writes:
>>> On Fri, Jul 12, 2013 at 3:28 AM, Magnus Hagander <magnus@hagander.net> wrote:
>>>> But I can understand the confusion - do you have a suggestion for how
>>>> to write it to make it more obvious what the actual problem is?
>>
>>> I don't think I communicated the problem right.
>>
>> Yeah, you did, but we need a concrete suggestion as to how to improve
>> the wording.
>
> Yeah. Well, I wanted to make sure I got my point across right before
> doing any suggestions.

Just FWIW, you did get it across fine to me at least :)


>> I wonder if just adding "in" would help:
>>
>> This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  In unsupported versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 /
7.3/ 7.2 / devel 
>
> That seems like a good suggestion to me.  Granted, this kind of user
> complaint is pretty rare to catch articulated, so it's hard to do much
> other than intuition...but I like it.

That would certainly be easy enough to do.

Another thought is should we somehow deal with 9.3 different
specifically? IIRC I've heard this complaint once before - and that
was during 9.2 beta... During "normal non-beta months", it's more
apparent - the problem here is, if I understand you correctly, that
9.3 is labeled as unsupported (which it is, but it made the person
think that the functionality would be unsupported once 9.3 is
*released*, which it certainly won't be).

So maybe a cross with Peters suggestoin whereby we somehow split it
into 3 groups - one that has supported versions, one that has
unsupported, and one that has development (which now would be devel
and 9.3).

Might that be even better?


--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Magnus Hagander <magnus@hagander.net> writes:
> So maybe a cross with Peters suggestoin whereby we somehow split it
> into 3 groups - one that has supported versions, one that has
> unsupported, and one that has development (which now would be devel
> and 9.3).

> Might that be even better?

Seems a bit verbose to me, but then again, I'm not one of the people
who is confused.

In any case, if we do change the wording, I'd like to lobby again
for using "obsolete" rather than "unsupported" for EOL versions.
That seems less likely to be misinterpreted.

            regards, tom lane

On Sun, Jul 14, 2013 at 5:22 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Magnus Hagander <magnus@hagander.net> writes:
>> So maybe a cross with Peters suggestoin whereby we somehow split it
>> into 3 groups - one that has supported versions, one that has
>> unsupported, and one that has development (which now would be devel
>> and 9.3).
>
>> Might that be even better?
>
> Seems a bit verbose to me, but then again, I'm not one of the people
> who is confused.
>
> In any case, if we do change the wording, I'd like to lobby again
> for using "obsolete" rather than "unsupported" for EOL versions.
> That seems less likely to be misinterpreted.

Obsolete would work fine for me from a wording perspective, but it's a
term I believe we don't use anywhere else. We are talking about
supported and EOL, but not obsolete. But if it makes things more
clear, it wouldn't be bad to invent a new term...

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

On Sun, Jul 14, 2013 at 5:42 PM, Michael Nolan <htfoot@gmail.com> wrote:
>
>
> On Sun, Jul 14, 2013 at 11:22 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>
>>
>>
>> In any case, if we do change the wording, I'd like to lobby again
>> for using "obsolete" rather than "unsupported" for EOL versions.
>> That seems less likely to be misinterpreted.
>
>
> I suggested the following wording:
>
> This page is for PostgreSQL version 9.2
> For the equivalent page in other versions see:
> Currently Supported Versions:  9.1,  9.0,  8.4
> Unreleased or Development versions: 9.3, Devel
> Older releases that are no longer being maintained: 8.3, 8.2, 8.1, 8.0
>
> Yes, it is more verbose, but the web is one place where space is not at a
> premium, and this is (IMHO) far clearer for the casual reader.

Actually, space "above the fold" *is* at a huge premium on the web.

If we put it at the bottom of the page your argument for space not at
a premium would be valid. But we really don't want anything using up
more than one row at the top.


> A separate issue is, when 9.3 goes live or 8.4 goes EOL, do these pages
> automatically get moved to the 'supported' or 'not maintained' sections,
> respectively, or do all these pages have to be revised?

That is all handled automatically.

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

On Mon, Jul 15, 2013 at 2:41 PM, Michael Nolan <htfoot@gmail.com> wrote:
>
>
> On Mon, Jul 15, 2013 at 4:52 AM, Magnus Hagander <magnus@hagander.net>
> wrote:
>>
>> On Sun, Jul 14, 2013 at 5:42 PM, Michael Nolan <htfoot@gmail.com> wrote:
>> >
>> >
>> > On Sun, Jul 14, 2013 at 11:22 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> >>
>> >>
>> >>
>> >> In any case, if we do change the wording, I'd like to lobby again
>> >> for using "obsolete" rather than "unsupported" for EOL versions.
>> >> That seems less likely to be misinterpreted.
>> >
>> >
>> > I suggested the following wording:
>> >
>> > This page is for PostgreSQL version 9.2
>> > For the equivalent page in other versions see:
>> > Currently Supported Versions:  9.1,  9.0,  8.4
>> > Unreleased or Development versions: 9.3, Devel
>> > Older releases that are no longer being maintained: 8.3, 8.2, 8.1, 8.0
>> >
>> > Yes, it is more verbose, but the web is one place where space is not at
>> > a
>> > premium, and this is (IMHO) far clearer for the casual reader.
>>
>> Actually, space "above the fold" *is* at a huge premium on the web.
>
>
> True, but 'how do I get to this page for some other version?' isn't the
> reason someone brings up a page, so it doesn't need to be above the fold.
> Prime space should be used for prime purposes.

The main reason that info line was added was that people arrive from
google quite often to a different version than the one they're using.


>> If we put it at the bottom of the page your argument for space not at
>> a premium would be valid. But we really don't want anything using up
>> more than one row at the top.
>
>
> Why do we need anything at all at the top regarding other versions? It is
> probably desirable to say what version a page is for as part of the overall
> description of what the page is about, and that can probably fit on one
> line.

See above.


>> > A separate issue is, when 9.3 goes live or 8.4 goes EOL, do these pages
>> > automatically get moved to the 'supported' or 'not maintained' sections,
>> > respectively, or do all these pages have to be revised?
>>
>> That is all handled automatically.
>
>
> I suspected as much, but what happens behind the curtain is not always
> obvious (nor does it need to be for 99% of the user community.)  Thanks for
> enlightening me.

Certainly. You can find the full code for how it's actually built on
http://git.postgresql.org/ in the project named "pgweb".

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

On Mon, Jul 15, 2013 at 10:51:13AM +0100, Magnus Hagander wrote:
> On Sun, Jul 14, 2013 at 5:22 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > Magnus Hagander <magnus@hagander.net> writes:
> >> So maybe a cross with Peters suggestoin whereby we somehow split it
> >> into 3 groups - one that has supported versions, one that has
> >> unsupported, and one that has development (which now would be devel
> >> and 9.3).
> >
> >> Might that be even better?
> >
> > Seems a bit verbose to me, but then again, I'm not one of the people
> > who is confused.
> >
> > In any case, if we do change the wording, I'd like to lobby again
> > for using "obsolete" rather than "unsupported" for EOL versions.
> > That seems less likely to be misinterpreted.
>
> Obsolete would work fine for me from a wording perspective, but it's a
> term I believe we don't use anywhere else. We are talking about
> supported and EOL, but not obsolete. But if it makes things more
> clear, it wouldn't be bad to invent a new term...

The problem with "obsolete" is that, in some way, 9.2 makes 9.1
obsolete, particularly when 9.2 greatly improves features 9.1 had.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

On Sun, Jul 14, 2013 at 11:04 AM, Magnus Hagander <magnus@hagander.net> wrote:
> On Sat, Jul 13, 2013 at 3:12 AM, Daniel Farina <daniel@heroku.com> wrote:
>> On Fri, Jul 12, 2013 at 5:44 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>> Daniel Farina <daniel@heroku.com> writes:
>>>> On Fri, Jul 12, 2013 at 3:28 AM, Magnus Hagander <magnus@hagander.net> wrote:
>>> I wonder if just adding "in" would help:
>>>
>>> This page in other versions: 9.2 / 9.1 / 9.0 / 8.4  |  In unsupported versions: 9.3 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 /
7.3/ 7.2 / devel 
>>
>> That seems like a good suggestion to me.  Granted, this kind of user
>> complaint is pretty rare to catch articulated, so it's hard to do much
>> other than intuition...but I like it.
>
> That would certainly be easy enough to do.
>
> Another thought is should we somehow deal with 9.3 different
> specifically? IIRC I've heard this complaint once before - and that
> was during 9.2 beta... During "normal non-beta months", it's more
> apparent - the problem here is, if I understand you correctly, that
> 9.3 is labeled as unsupported (which it is, but it made the person
> think that the functionality would be unsupported once 9.3 is
> *released*, which it certainly won't be).
>
> So maybe a cross with Peters suggestoin whereby we somehow split it
> into 3 groups - one that has supported versions, one that has
> unsupported, and one that has development (which now would be devel
> and 9.3).

I have applied a patch that splits the list into three groups -
supported versions, development versions (9.3beta + devel) and
unsupported versions.

As a bonus, this forced me to fix the datamodel underlying it enough
that it's now possible to report bugs in beta versions in the bugs
form, which has also been requested quite a few times.


--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

On Sat, Aug 17, 2013 at 04:06:10PM +0200, Magnus Hagander wrote:
> I have applied a patch that splits the list into three groups -
> supported versions, development versions (9.3beta + devel) and
> unsupported versions.

I like having the 'devel' docs available there.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

On Tue, Aug 20, 2013 at 9:29 AM, Chris Travers <chris.travers@gmail.com> wrote:
> As we move towards 9.4, would it be worthwhile suggesting that we break this
> out into "Obsolete Versions" and "Forthcoming" or similar?

I really don't think we need any more classifications. And you're
going to end up needing a very wide screen to see it all...

When 9.3 is released, it will move from "development" to "supported".
9.4 will stay under "devel" because, well, it's in development. Once
9.4 hits beta it will get it's own number under "development", which
will be moved to "supported" once that one is released.


--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/