On Thu, Nov 12, 2020 at 10:21:02AM +0800, Craig Ringer wrote:
> Here's how the rendered docs look: https://imgur.com/a/VyjzEw5
>
> Think. You're used to recovery.conf. You've recently switched to pg 12. You
> search for "recovery.conf" or "primary_slot_name" or "standby_mode" or
> something. You of course land up at https://www.postgresql.org/docs/11/
> recovery-config.html or another version.
>
> What do you do now? There's no "12" or "current" link for your version. You
> don't follow postgres development closely, and you have no idea we removed the
> file. You might work it out from the release notes. But even then, if you try
> searching for "standby_mode" in the updated docs will tell you basically
> nothing, it has just vanished
>
> Also by simply deleting the page, we've broken web links to https://
> www.postgresql.org/docs/current/recovery-config.html
>
> So there are three really good reasons:
>
> * Help users of the web docs navigate to the right place when we remove things
> * Don't break web links (breaking links without redirects is bad, the web is
> sad)
> * Help upgrading users who know the old terms find the new terms
>
> I'd welcome your suggestions on other ways to arrange this, so long as it meets
> the basic requirement "retain the linktable target 'recovery-config' "
This is certainly not the first or last time we will rename things.
Fortunately, this has already been discussed in the renaming of default
roles to predefined roles:
https://www.postgresql.org/message-id/flat/157742545062.1149.11052653770497832538%40wrigleys.postgresql.org
This naming change has not happened yet, even though the issue is 11
months old, but the agreed-upon way to handle this is to use a website
redirect that links to the new text. You can add a "tip" there so they
understand the renaming has happened.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
