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 <br...@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee