Documentation Improvement suggestions

On Mon, 20 Jul 2009 09:34:00 -0400
Robert James <srobertjames@gmail.com> wrote:

Two small suggestions that might make it easier for newcomers to
take advantage of the wonderful database:
1. Googling Postgres docs produces links for all different
versions. This is because incoming links are to different
versions. Besides being confusing, it pushes the pages lower in
Google, and makes it harder to find them.
Could the website offer a link to the 'current' version, whichever
it is. Eg instead of just :
http://www.postgresql.org/docs/8.1/static/creating-cluster.html
Have:
http://www.postgresql.org/docs/current/static/creating-cluster.html
which would keep all incoming links pointed to the current page.

Did you actually tried the link you proposed?
There is a page behind it... ant it actually links to 8.4 docs.
People still need old docs so you can't just make docs for previous
versions unavailable... and once they are available, they will be
indexed.
Unfortunately current version doesn't mean most used.

Actually what I'd enjoy is a link to the "interactive" version and
maybe aggregating all the comments of previous versions in
the new version (indicating from which versions they come from).

--
Ivan Sergio Borgonovo
http://www.webthatworks.it

Robert James escribi�:

Two small suggestions that might make it easier for newcomers to take
advantage of the wonderful database:
1. Googling Postgres docs produces links for all different versions. This
is because incoming links are to different versions. Besides being
confusing, it pushes the pages lower in Google, and makes it harder to find
them.
Could the website offer a link to the 'current' version, whichever it is.
Eg instead of just :
http://www.postgresql.org/docs/8.1/static/creating-cluster.html
Have:
http://www.postgresql.org/docs/current/static/creating-cluster.html
which would keep all incoming links pointed to the current page.

Maybe we should offer a robots.txt file that told crawlers to only index
the "current" version of the docs, not the version-specific ones.

2. The 'SQL' in 'PostgresSQL' is hard to say and type. Everyone drops it
(even this list!). Why not change the official name? Again, it would make
googling and naming things easier.

This is a taboo topic which has created the largest holy wars I've seen
in this project. Please don't raise it. If you're interested, search
the archives.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On Mon, Jul 20, 2009 at 5:14 PM, Alvaro
Herrera<alvherre@commandprompt.com> wrote:

Robert James escribió:

Two small suggestions that might make it easier for newcomers to take
advantage of the wonderful database:
1. Googling Postgres docs produces links for all different versions.  This
is because incoming links are to different versions.  Besides being
confusing, it pushes the pages lower in Google, and makes it harder to find
them.
Could the website offer a link to the 'current' version, whichever it is.
 Eg instead of just :
http://www.postgresql.org/docs/8.1/static/creating-cluster.html
Have:
http://www.postgresql.org/docs/current/static/creating-cluster.html
which would keep all incoming links pointed to the current page.

Maybe we should offer a robots.txt file that told crawlers to only index
the "current" version of the docs, not the version-specific ones.

I don't see this is a good idea, if you want to google only for a
specific version
you can use ''site'' expression to filter your results

site:http://www.postgresql.org/docs/8.4/ foo

On Mon, Jul 20, 2009 at 11:14:27AM -0400, Alvaro Herrera wrote:

Robert James escribió:

Could the website offer a link to the 'current' version, whichever it is.
Eg instead of just :
http://www.postgresql.org/docs/8.1/static/creating-cluster.html
Have:
http://www.postgresql.org/docs/current/static/creating-cluster.html
which would keep all incoming links pointed to the current page.

Maybe we should offer a robots.txt file that told crawlers to only index
the "current" version of the docs, not the version-specific ones.

I know it's not easy, but a nice option to me would be if the 8.1 docs
page linked to the equivalent page in the other versions. That would
avoid the need to manually edit the URL after a google search.

Oh, and +10 for the "Up" link at the top of the page also.

Have a nice day,
--
Martijn van Oosterhout <kleptog@svana.org> http://svana.org/kleptog/

On Mon, Jul 20, 2009 at 11:37 AM, Martijn van Oosterhout
<kleptog@svana.org>wrote:

I know it's not easy, but a nice option to me would be if the 8.1 docs
page linked to the equivalent page in the other versions. That would
avoid the need to manually edit the URL after a google search.

Oh, and +10 for the "Up" link at the top of the page also.

+1 (!)
This would solve all of the docs problems I mentioned - include a line at
the top stating "This is the documentation for version 8.1. Hyperlink:See
documentation of current version (8.4)".
And, yes, an "Up" at the top would be super helpful - reduce about 50% of
searches.