Re: Add docs stub for recovery.conf

On Thu, Nov 12, 2020 at 3:44 AM Bruce Momjian <bruce(at)momjian(dot)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.
>

I explained why.

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' "

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.