Greetings, * Bruce Momjian (br...@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
signature.asc
Description: PGP signature
