Re: Add docs stub for recovery.conf - Mailing list pgsql-hackers

Greetings,

* Bruce Momjian (bruce@momjian.us) wrote:
> 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.

Indeed, we've renamed things a number of times before, eg:

https://www.postgresql.org/docs/current/pgwaldump.html

where the 9.6 link goes to:

https://www.postgresql.org/docs/9.6/pgxlogdump.html

and the 'current' link from the 9.6 page goes to the pgwaldump page,
which all works pretty well, if all you're looking at is our
documentation and not considering external links into the documentation.

However, that isn't what Craig's raising a concern over here (at least,
not exclusively), it's this issue:

https://www.postgresql.org/docs/current/pgxlogdump.html

Which currently goes to a 404.

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.

> 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.

That rename will suffer the same problem that Craig is concerned about
here regarding the 'current' link, once it's done.  I tend to agree with
Craig that it'd be good to improve on this situation, and I've reached
out to Jonathan to ask about using his new feature to have those
/current/ links redirect to the renamed page.  I'm actually wondering if
maybe we should just always do that for all the dog page aliases..

Might make more sense to discuss this over on -www though.

Thanks,

Stephen