Re: Add docs stub for recovery.conf

On Fri, Nov 13, 2020 at 11:50 AM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> > So you are saying you don't think you are getting sufficient thought
> > into your proposal, and getting just a reflex? Just because we don't
> > agree with you don't mean we didn't think about it. In fact, we have
> > thought about it a lot, which is evident from the URL I sent you
> > already.
>

I am mostly trying to say that I don't think the issues I raised were
actually addressed in the proposed alternatives. I put in a fair bit of
effort to clearly set out the problem that this is meant to solve, and was
frustrated to perceive the response as "yeah, nah, lets just do this other
thing that only addresses one part of the original issue." It wasn't clear
why my proposal appeared to be being rejected. Perhaps I didn't fully grasp
the context of the linked discussion.

Please review the docs on standbys with a "new user" hat on. It's confusing
( though the new front-matter and definitions in the HA chapter help) even
without upgrade considerations. See how long it takes you to determine the
answer to the question "what exactly puts a server into 'standby mode' " ?

This proposal was intended to address one part of that, stemming directly
from my own challenges with the docs when I as an experienced PostgreSQL
user and contributor went to adapt some tests to Pg 12 and 13. I knew we'd
removed recovery.conf, but for the life of me I couldn't remember how to
put the server in standby mode in 12 or 13 at the time (I've been working
with 11 too much lately)... and it took ages to actually find that in the
docs.

I can be pretty dense sometimes, but if it sent me for a loop it's going to
confuse others a great deal. Two things that would've helped me would've
been some cross references to the old configuration terms, and a
non-vanishing documentation URL for newer versions. Hence this proposal.

What would be interesting, I think you were suggesting this, is a
> separate doc chapter that had a list of all the renames, what version
> they were renamed in, and a link from their to the new name in the docs.
>

Right, that is exactly what I am suggesting we add, as an appendix so it's
way out of the way of the main flow of the docs. Per the original patch and
the illustrative screenshots. I called it something like "removed and
renamed features and settings" or something in the proposed patch.
Alternatives would be welcomed, I don't like the name much.

This could be easily created by reading the old release notes. Anyone
> looking for old names would automatically be sent to that page in the
> docs. This would give us a definitive list, and make the list out of
> the main flow of the docs.
>

Exactly. Plus a few <indexterm>s where appropriate. That's pretty much all
I'm after.