On Thu, Nov 12, 2020 at 3:44 AM Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote: > Hi all > > I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for > it were removed completely as well. That's largely sensible, but is confusing > when users have upgraded and are trying to find out what happened, or how to > configure equivalent functionality.
I don't see the logic in carrying doc stuff that we don't have anymore.
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
* 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' "
In general I think it's quite unpleasant for users to have docs sections just vanish. I strongly suggest that we enact a policy going forwards that any <chapter> or <sect1> removal should be accompanied by a redirect or stub that helps users find the new contents. It regularly annoys me when I'm trying to navigate around various versions of the docs and things just vanish.
