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

Greetings,

* Stephen Frost (sfrost@snowman.net) wrote:
> * 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.

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.

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.

I'm continuing to chat with Jonathan about if it'd make sense to do the
same for the other doc aliases.

Thanks,

Stephen