10

PostgreSQL has extremely helpful online documentation. I wonder about the various ways to link to the manual.

Available sites

There is a static home page without user comments for every major point-release:
http://www.postgresql.org/docs/9.0/static/
http://www.postgresql.org/docs/9.1/static/
...

There is also a variant that includes (moderated) comments on the bottom of each page:
http://www.postgresql.org/docs/9.0/interactive/
http://www.postgresql.org/docs/9.1/interactive/
...

And there is the URL for to the latest release at any given time, static or interactive:
http://www.postgresql.org/docs/current/static/
http://www.postgresql.org/docs/current/interactive/

The pattern of the links has been stable for years. For any given link you get the corresponding chapter in another version by substituting the version number or 'current' (unless the feature has been dropped):
http://www.postgresql.org/docs/8.4/static/sql-copy.html
http://www.postgresql.org/docs/current/static/sql-copy.html

The /interactive branch is now permanently available. (There were dead links for old versions at first.)

Since December 2011 the development docs have been relocated to fit into this regime: http://www.postgresql.org/docs/devel/static/
(no /interactive branch)

What to use?

More often than not I can link to a chapter of the manual in my answers.

As long as you have to refer to a specific version this question does not apply. But if the answer isn't version-specific or the version is unknown, then you have to pick. So far I mostly use http://www.postgresql.org/docs/current/static/. A gotcha with that is, when you start at /current and browse the manual, you end up at /9.1 or whatever is current. When you copy the link then you have to edit in '/current' again.
Its amazing how few people even mention their program version in questions. On a programmer's site you'd think they know better.

Specific questions:

Considering bit rot, should somebody who looks at an answer three years from now get the manual for the same or the then current version?
Should authors who care follow a canonical way?
What warrants an edit on somebody else's posts?
Do you even think it matters much?
What's your rationale?

I guess this goes on meta, not main - even if the tag is not available here. The question is aimed at SO, but applies to any site, really, where PostgreSQL is on topic. There must exist related considerations for other projects?

3
  • Seems like you should default to the latest documentation, but if you are referring to a previous version, then link to that version's documentation. Interactive seems a better choice than static, as it will have more information. No, this isn't perfect, but how can you be?
    – user1228
    Commented Oct 7, 2011 at 20:12
  • @Won'tಠ_ಠ: I forgot to mention, the /interactive branch of the docs is dropped at end-of-life. Added that piece in the question. Would you still favor /interactive over /static? Commented Oct 7, 2011 at 20:27
  • I guess not....
    – user1228
    Commented Oct 7, 2011 at 20:52

2 Answers 2

7

FWIW, I've worked with the PostgreSQL Web Team in the past, and the general idea behind how I think it should be used is this:

In general, you should point to the /current version of the docs, and preferably to the /interactive version. This allows the link to perpetuate in the majority of cases, it increases the ranking of the /current branch of the docs within search engines, comments can be used to expand on the information in the docs, and they can also be culled for inclusion in the docs proper when needed.

Now, if the answer is version specific, or refers to an older version where the information would no longer apply within /current/, then you should point to a specific version.

There are cases where this means a link to the docs could break in the future, but that's ok. In many of those cases, it likely means that there is a new answer to the problem, so it's best that the question be re-evaluated, and then the link can be modified based on the criteria above.

0
2

Note that things have changed since. The /static and /interactive branches have been removed, and there are links to other versions of the same chapter at the top of each manual page.

And it's all HTTPS now, of course. So:

https://www.postgresql.org/docs/current/sql-copy.html

Also, release notes are only included for the current major version. Other release notes in the respective version of the manual.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .