Re: Add docs stub for recovery.conf

On Thu, Nov 12, 2020 at 11:25 PM Stephen Frost <sfrost(at)snowman(dot)net> wrote:

>
> > Now, the pgweb feature that Jonathan wrote recently might actually be
> > exactly what we need to fix that, and to address the issue with
> > recovery config documentation that Craig raises.
>
> After chatting with Jonathan about this for a bit and testing it out in
> our test environment, I've gone ahead and added an entry for
> pgxlogdump.html to redirect to pgwaldump.html, and that seems to be
> working well.
>

Thanks.

With that then- Craig, can you look at how the pgxlogdump -> pgwaldump
> pages work and see if using that would address the concerns you've
> raised here..?
>

> Though we need to decide which page 'recovery-config' should go to in
> newer versions.
>

Since we basically vanished all evidence of the old configuration, I don't
think there is a suitable place.

I maintain that simply vanishing terms from the docs without any sort of
explanation is a user-hostile action that we should fix and stop doing If
we had something in the docs and we remove it, it's not unduly burdensome
to have some index entries that point to the replacement/renamed terms, and
a short appendix entry explaining what happened.

If that is for some reason unacceptable (and I don't see anyone giving any
actual reason why) the closest I can come up with is probably redirecting
to
https://www.postgresql.org/docs/current/warm-standby.html#STANDBY-SERVER-OPERATION
. But that needs to be fixed to actually explicitly state what makes a
standby server into a standby server (per my patch), since right now it
just kind of assumes you know about standby.signal .

But... fiddling with the website addresses none of my other concerns. In
particular, it doesn't help a user understand that "standby_mode" is gone
and to look for "standby.signal" instead. It doesn't provide any "see also"
pointers for old terms to point to new terms in the index. Website
redirects won't help users with local copies of the docs or manpages who
are wondering what the heck happened to recovery.conf and standby_mode
either.

So I still think this needs a docs patch. Redirects on the website are not
sufficient. If you don't like how I spelled it, consider calling it
"important incompatible changes" or something.

The release notes are IMO not sufficient for this because (a) they don't
appear in the index; (b) you have to know something has been
removed/changed before you know to look in the relnotes for it; (c) you
have to find the relnotes for the correct release to find the info you
want. An appendix covering important renamings, removals and other
incompatible changes would address all those points *and* fix the web
links, man page names, etc.

Can anyone tell me why the solution I proposed is not acceptable, and why
we have to invent a different one instead? The website redirect is good
and all, but doesn't really solve the problem, and I still don't know
what's wrong with just fixing the docs...