Thread: Adding links to alternate versions of doc pages

(Prompted by Bruce Momjian's post at http://momjian.us/main/blogs/pgblog/2012.html#March_27_2012, this message is adapted from my comment there)

I have one big frustration with the Postgres documentation, and that's its interface from Google.  
 
Say I want to look up information about maintenance_work_mem. I go to Google and search for "postgres maintenance_work_mem". I get page a page of results (https://www.google.com/search?q=postgresql+maintenance_work_mem) and three of the first four hits are, as one might expect, links to the Postgres docs website.
 
The problem is that those three pages in the top four hits are to docs for older versions of Postgres: 8.0, 8.3 and 8.4. Based on how Google's page ranking work, the older pages will always be the highest ranking.  The older pages become more established and rank higher as time goes on.  
 
This problem of linking to old pages in the documentation corpus isn't only for people coming in from Google. Search postgresql.org through its search box (http://www.postgresql.org/search/?q=maintenance_work_mem) and you still get the same mishmash of versions of pages.  I'm focusing mostly on Google, however, because I'll bet a shiny new dime that the vast majority of hits on the postgresql.org docs are from external search engines, not the internal one.
 
So I'm linked to an old version of the page in question.  I'm aware of this, and I can account for it. If I go click on http://www.postgresql.org/docs/8.3/static/runtime-config-resource.html, I know the page is not the latest (although maybe not every user will). I know that if I want the latest version of that page, or the version that applies to the Postgres that I'm running, I have to manually tweak the URL to change "/8.3/" to "/current/" or "/9.0/" or whatever version I want to see.  
 
What I would love love LOVE to see would be a dropdown by the "Home → Documentation → Manuals → PostgreSQL 8.3" where I'm able to choose from other versions easily. Or maybe it will be a list of other versions of this document available, hyperlinked to them.  It would also help the casual reader know that there are multiple versions of the docs on the site by making it explicitly clear through those visual signposts "Hey, this isn't the only version of this page available, and perhaps you want a more current one."  

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


> What I would love love LOVE to see would be a dropdown by the
> "Home â Documentation â Manuals â PostgreSQL 8.3" where I'm
> able to choose from other versions easily. Or maybe it will
> be a list of other versions of this document available,
> hyperlinked to them.  It would also help the casual reader
> know that there are multiple versions of the docs on the
> site by making it explicitly clear through those visual
> signposts "Hey, this isn't the only version of this page
> available, and perhaps you want a more current one."
>
> I'm here to both make this suggestion as a user of the docs,
> and to volunteer my time to help make it happen.

Big +1 from me. The -docs list is pretty lonely, but I cannot see anyone
objecting to this. You might post to -general if you want
someone besides me to reply, ha ha ha!

- --
Greg Sabino Mullane greg@turnstep.com
PGP Key: 0x14964AC8 201203281250
http://biglumber.com/x/web?pk=2529DF6AB8F79407E94445B4BC9B906714964AC8
-----BEGIN PGP SIGNATURE-----

iEYEAREDAAYFAk9zQWkACgkQvJuQZxSWSshz4QCgp113EmuIUtzAmzNzIV3EdS1Z
h4UAoOFOj3NHhV08+i9kigcb4/EBlTyn
=6Wgt
-----END PGP SIGNATURE-----

On 28.03.2012 19:51, Greg Sabino Mullane wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: RIPEMD160
>
>
>> What I would love love LOVE to see would be a dropdown by the
>> "Home â Documentation â Manuals â PostgreSQL 8.3" where I'm
>> able to choose from other versions easily. Or maybe it will
>> be a list of other versions of this document available,
>> hyperlinked to them.  It would also help the casual reader
>> know that there are multiple versions of the docs on the
>> site by making it explicitly clear through those visual
>> signposts "Hey, this isn't the only version of this page
>> available, and perhaps you want a more current one."
>>
>> I'm here to both make this suggestion as a user of the docs,
>> and to volunteer my time to help make it happen.
>
> Big +1 from me. The -docs list is pretty lonely, but I cannot see anyone
> objecting to this. You might post to -general if you want
> someone besides me to reply, ha ha ha!

I totally agree, I am often google annoyed by this, too. Patch, please ;-)

--
   Heikki Linnakangas
   EnterpriseDB   http://www.enterprisedb.com

Excerpts from Greg Sabino Mullane's message of mié mar 28 16:51:06 UTC 2012:
>
> Hash: RIPEMD160
>
> > What I would love love LOVE to see would be a dropdown by the
> > "Home â Documentation â Manuals â PostgreSQL 8.3" where I'm
> > able to choose from other versions easily. Or maybe it will
> > be a list of other versions of this document available,
> > hyperlinked to them.  It would also help the casual reader
> > know that there are multiple versions of the docs on the
> > site by making it explicitly clear through those visual
> > signposts "Hey, this isn't the only version of this page
> > available, and perhaps you want a more current one."
> >
> > I'm here to both make this suggestion as a user of the docs,
> > and to volunteer my time to help make it happen.
>
> Big +1 from me.

+1

Need to make clear where the tweak is going to happen -- obviously the
HTML generated from the SGML source will not contain the links.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On Wed, Mar 28, 2012 at 9:51 AM, Greg Sabino Mullane <greg@turnstep.com> wrote:
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: RIPEMD160
>
>
>> What I would love love LOVE to see would be a dropdown by the
>> "Home â Documentation â Manuals â PostgreSQL 8.3" where I'm
>> able to choose from other versions easily. Or maybe it will
>> be a list of other versions of this document available,
>> hyperlinked to them.  It would also help the casual reader
>> know that there are multiple versions of the docs on the
>> site by making it explicitly clear through those visual
>> signposts "Hey, this isn't the only version of this page
>> available, and perhaps you want a more current one."
>>
>> I'm here to both make this suggestion as a user of the docs,
>> and to volunteer my time to help make it happen.
>
> Big +1 from me. The -docs list is pretty lonely, but I cannot see anyone
> objecting to this. You might post to -general if you want
> someone besides me to reply, ha ha ha!

+1. I also find this annoying.

gabrielle

On Wed, Mar 28, 2012 at 20:24, Alvaro Herrera
<alvherre@commandprompt.com> wrote:
>
> Excerpts from Greg Sabino Mullane's message of mié mar 28 16:51:06 UTC 2012:
>>
>> Hash: RIPEMD160
>>
>> > What I would love love LOVE to see would be a dropdown by the
>> > "Home â Documentation â Manuals â PostgreSQL 8.3" where I'm
>> > able to choose from other versions easily. Or maybe it will
>> > be a list of other versions of this document available,
>> > hyperlinked to them.  It would also help the casual reader
>> > know that there are multiple versions of the docs on the
>> > site by making it explicitly clear through those visual
>> > signposts "Hey, this isn't the only version of this page
>> > available, and perhaps you want a more current one."
>> >
>> > I'm here to both make this suggestion as a user of the docs,
>> > and to volunteer my time to help make it happen.
>>
>> Big +1 from me.
>
> +1
>
> Need to make clear where the tweak is going to happen -- obviously the
> HTML generated from the SGML source will not contain the links.

You can add the dropdown fairly easily in the website code. However,
that assumes that no pages have *changed filenames* between versions.
Which is not true. That would either drop those versions from the
list, or generate a 404. I'm not sure how to create some sort of
mapping between versions that would actually work without being
actively maintained (and if it has to be actively maintained, it will
go out of date).

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

On 28-03-2012 16:14, Magnus Hagander wrote:
> I'm not sure how to create some sort of
> mapping between versions that would actually work without being
> actively maintained (and if it has to be actively maintained, it will
> go out of date).
>
I can't find it in pgweb but isn't there a XML file or a config file
containing the maintained doc versions?


--
   Euler Taveira de Oliveira - Timbira       http://www.timbira.com.br/
   PostgreSQL: Consultoria, Desenvolvimento, Suporte 24x7 e Treinamento

On Wed, Mar 28, 2012 at 22:02, Euler Taveira <euler@timbira.com> wrote:
> On 28-03-2012 16:14, Magnus Hagander wrote:
>> I'm not sure how to create some sort of
>> mapping between versions that would actually work without being
>> actively maintained (and if it has to be actively maintained, it will
>> go out of date).
>>
> I can't find it in pgweb but isn't there a XML file or a config file
> containing the maintained doc versions?

There is a list of such versions yes.

But the same page may have a different filename (thus URL) in
different versions, due to the docs being restructured.

Finding the version is easy. Figuring out what the actual URL is in
the 5 years old version is the hard part.


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

On Wed, Mar 28, 2012 at 22:08, Magnus Hagander <magnus@hagander.net> wrote:
> On Wed, Mar 28, 2012 at 22:02, Euler Taveira <euler@timbira.com> wrote:
>> On 28-03-2012 16:14, Magnus Hagander wrote:
>>> I'm not sure how to create some sort of
>>> mapping between versions that would actually work without being
>>> actively maintained (and if it has to be actively maintained, it will
>>> go out of date).
>>>
>> I can't find it in pgweb but isn't there a XML file or a config file
>> containing the maintained doc versions?
>
> There is a list of such versions yes.

I should say, but forgot to, that this list is in the database, it's
not in an XML file. There'a  view that generates an XML of it on the
web, but internally it's stored in the database.


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

On 28-03-2012 17:08, Magnus Hagander wrote:
> I should say, but forgot to, that this list is in the database, it's
> not in an XML file. There'a  view that generates an XML of it on the
> web, but internally it's stored in the database.
>
Hmmm. I didn't look at the database schema but what if we get versions per
last-part-of-url? It isn't a perfect solution (because (i) some URLs are
renamed along the versions and (ii) some parts get their own page) but it will
cover almost all cases.


--
   Euler Taveira de Oliveira - Timbira       http://www.timbira.com.br/
   PostgreSQL: Consultoria, Desenvolvimento, Suporte 24x7 e Treinamento

On ons, 2012-03-28 at 21:14 +0200, Magnus Hagander wrote:
> You can add the dropdown fairly easily in the website code. However,
> that assumes that no pages have *changed filenames* between versions.
> Which is not true. That would either drop those versions from the
> list, or generate a 404. I'm not sure how to create some sort of
> mapping between versions that would actually work without being
> actively maintained (and if it has to be actively maintained, it will
> go out of date).

Not that those cross-version links wouldn't be useful (in fact, I often
would like to have them when starting at the latest version going
backwards), but they don't really solve the underlying problem.  I don't
really believe that it is a general search engine behavior to always
prefer the oldest resource among alternatives.  For example, if I search
for something like "presidential elections", I surely don't get links to
the oldest presidential election on record.

A related problem: At least a search on Google will usually find the
documentation of some old version.  A search on Bing, however, doesn't
find the documentation at all.  That indicates to me that there is
something seriously wrong in how the web site is constructed.

On Thursday, March 29, 2012, Peter Eisentraut <peter_e@gmx.net> wrote:
> On ons, 2012-03-28 at 21:14 +0200, Magnus Hagander wrote:
>> You can add the dropdown fairly easily in the website code. However,
>> that assumes that no pages have *changed filenames* between versions.
>> Which is not true. That would either drop those versions from the
>> list, or generate a 404. I'm not sure how to create some sort of
>> mapping between versions that would actually work without being
>> actively maintained (and if it has to be actively maintained, it will
>> go out of date).
>
> Not that those cross-version links wouldn't be useful (in fact, I often
> would like to have them when starting at the latest version going
> backwards), but they don't really solve the underlying problem.  I don't
> really believe that it is a general search engine behavior to always
> prefer the oldest resource among alternatives.  For example, if I search
> for something like "presidential elections", I surely don't get links to
> the oldest presidential election on record.
>
> A related problem: At least a search on Google will usually find the
> documentation of some old version.  A search on Bing, however, doesn't
> find the documentation at all.  That indicates to me that there is
> something seriously wrong in how the web site is constructed.

Works for me. Aside from the version issue, I get very relevant results for a few test searches on Bing.

--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On tor, 2012-03-29 at 18:12 +0100, Dave Page wrote:
> > A related problem: At least a search on Google will usually find the
> > documentation of some old version.  A search on Bing, however, doesn't
> > find the documentation at all.  That indicates to me that there is
> > something seriously wrong in how the web site is constructed.
>
> Works for me. Aside from the version issue, I get very relevant results for
> a few test searches on Bing.

Hmm, interesting.  I tried the example given at the beginning of this
thread "postgresql maintenance_work_mem", which didn't work so well.
("postgres maintenance_work_mem" is even worse.)  Other searches appear
to work better and in most cases even prefer the current documentation
link.

Still, the overall quality of the results is quite bad.

I'm gratified to see such positive feedback on my idea.

On Mar 29, 2012, at 10:07 AM, Peter Eisentraut wrote:

> On ons, 2012-03-28 at 21:14 +0200, Magnus Hagander wrote:
>> You can add the dropdown fairly easily in the website code. However,
>> that assumes that no pages have *changed filenames* between versions.
>> Which is not true. That would either drop those versions from the
>> list, or generate a 404. I'm not sure how to create some sort of
>> mapping between versions that would actually work without being
>> actively maintained (and if it has to be actively maintained, it will
>> go out of date).
>
> Not that those cross-version links wouldn't be useful (in fact, I often
> would like to have them when starting at the latest version going
> backwards),

Yup. I often end up editing the URL to compare the same page
across several versions. Links would be nice.

> but they don't really solve the underlying problem.  I don't
> really believe that it is a general search engine behavior to always
> prefer the oldest resource among alternatives.  For example, if I search
> for something like "presidential elections", I surely don't get links to
> the oldest presidential election on record.

For a random search ("postgresql current_timestamp") I'm getting
versions 8.1 and 8.0 on Google, version 8.1 on Bing. No mention of
current or anything newer than 8.1 on the first page of either.

>
> A related problem: At least a search on Google will usually find the
> documentation of some old version.  A search on Bing, however, doesn't
> find the documentation at all.  That indicates to me that there is
> something seriously wrong in how the web site is constructed.

rel="canonical" is one way to tell search engines to look at one
particular page as the canonical version.

Having all the specific-version pages use that to point to the
non-version URL might help.

The existing priority stuff in the sitemap should help with this,
but it doesn't seem to.

I'm assuming someone has checked the google webmaster
tools reports for the site, to see if there's anything interesting
there.

Cheers,
  Steve

On Thu, Mar 29, 2012 at 6:36 PM, Andy Lester <andy@petdance.com> wrote:
>
> On Mar 28, 2012, at 2:11 PM, gabrielle wrote:
>
> +1. I also find this annoying.
>
>
> I'm gratified to see such positive feedback on my idea.
>
> Now, who of you can help me understand the existing system so that I can
> look into what I have to do to implement these changes?

The docs pages are rendered using the Django template here:

http://git.postgresql.org/gitweb/?p=pgweb.git;a=blob;f=templates/docs/docspage.html;h=f40ef89ed957ad0a83a484298d39c2a5bba1cdf5;hb=5d3a6f7a38670e522e2d33725476e525f9f2c357
by the backend code here:

http://git.postgresql.org/gitweb/?p=pgweb.git;a=tree;f=pgweb/docs;h=c227a13f0a87dd5707abf5f11af0e6248621e984;hb=5d3a6f7a38670e522e2d33725476e525f9f2c357
(views.py is the place to look).


--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Thu, Mar 29, 2012 at 9:11 PM, Andy Lester <andy@petdance.com> wrote:
>
> On Mar 29, 2012, at 1:10 PM, Dave Page wrote:
>
> The docs pages are rendered using the Django template here:
>
>
> That's a start.  Thanks.
>
> When I have questions about infrastructure, can I ask you for help, Dave?
>  Or should I keep posting stuff here to pgsql-docs?  I imagine it'll be
> pretty annoying having this list be our personal collaboration space.

You should post to pgsql-www. I don't really know Django/Python yet,
so won't be of much help.

--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Thu, Mar 29, 2012 at 12:58, Steve Atkins <steve@blighty.com> wrote:
>
> On Mar 29, 2012, at 10:07 AM, Peter Eisentraut wrote:
>> A related problem: At least a search on Google will usually find the
>> documentation of some old version.  A search on Bing, however, doesn't
>> find the documentation at all.  That indicates to me that there is
>> something seriously wrong in how the web site is constructed.

What we were told earlier was "just add a sitemap with relative
weights and that should fix it". Well, we now have a sitemap with
relative weights, and it has made pretty much no effect at all (but a
fair amount of work was unfortunately spent in building it :S)

We can use it to *remove* the older versions so it only hits on
current, but that's not really what we want.


> rel="canonical" is one way to tell search engines to look at one
> particular page as the canonical version.

We could make that for the root docs link, but is it generally smart
enough to realize that any sublinks in those docs are *also* the
canonical versions? I doubt it, but I don't know enough about
google...


> Having all the specific-version pages use that to point to the
> non-version URL might help.

Ah, you mean basically a link on every page going back to /current/?

That does bring back the whole problem of filenames/URLs being
different between different versions of course..


> The existing priority stuff in the sitemap should help with this,
> but it doesn't seem to.

Exactly.


> I'm assuming someone has checked the google webmaster
> tools reports for the site, to see if there's anything interesting
> there.

I have, and not found anything interesting. But I'm happy to admit I
don't really know what I'd be looking for :-)


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

On Mar 30, 2012, at 6:47 AM, Magnus Hagander wrote:

> On Thu, Mar 29, 2012 at 12:58, Steve Atkins <steve@blighty.com> wrote:
>
>> Having all the specific-version pages use that to point to the
>> non-version URL might help.
>
> Ah, you mean basically a link on every page going back to /current/?
>
> That does bring back the whole problem of filenames/URLs being
> different between different versions of course..

Yup. It's much the same issue, so it'd be something to try as part
of the "add links to other versions" exercise. Simpler, as it'd be reasonable
to add rel="canonical" pointing to the current page only if the versioned
page has the identical filename.

i.e. /docs/<version>/<static-or-not>/tutorial-start.html would have
<link rel="canonical" href="http://www.postgresql.org/current/static/tutorial-start.html">
in it's <head> for all versions, including the most recent.

It's sort of lying to the search engine categorizer, but might hint
it to do what we'd like. Whether it's a good idea or not, I'm not sure.
It'd be nice to get some hints from someone who understands SEO.

Cheers,
  Steve

On Fri, Mar 30, 2012 at 13:09, Steve Atkins <steve@blighty.com> wrote:
>
> On Mar 30, 2012, at 6:47 AM, Magnus Hagander wrote:
>
>> On Thu, Mar 29, 2012 at 12:58, Steve Atkins <steve@blighty.com> wrote:
>>
>>> Having all the specific-version pages use that to point to the
>>> non-version URL might help.
>>
>> Ah, you mean basically a link on every page going back to /current/?
>>
>> That does bring back the whole problem of filenames/URLs being
>> different between different versions of course..
>
> Yup. It's much the same issue, so it'd be something to try as part
> of the "add links to other versions" exercise. Simpler, as it'd be reasonable
> to add rel="canonical" pointing to the current page only if the versioned
> page has the identical filename.
>
> i.e. /docs/<version>/<static-or-not>/tutorial-start.html would have
> <link rel="canonical" href="http://www.postgresql.org/current/static/tutorial-start.html">
> in it's <head> for all versions, including the most recent.

Yeah, it seems to be a much "safer" thing, because it's not actually
shown in the UI, so it's not critical if we miss a page or two.

And yes, we can easily include a check in the page if a page exists
with the exact same name in "current".


> It's sort of lying to the search engine categorizer, but might hint
> it to do what we'd like. Whether it's a good idea or not, I'm not sure.
> It'd be nice to get some hints from someone who understands SEO.

yeah, I think unless we have that, it's all just speculation anyway...
And probably not worth putting too much work into on a pure gamble.

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