Add docs stub for recovery.conf

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
45 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Add docs stub for recovery.conf

Craig Ringer-5
Hi all

I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for it were removed completely as well. That's largely sensible, but is confusing when users have upgraded and are trying to find out what happened, or how to configure equivalent functionality.

https://www.postgresql.org/docs/11/recovery-config.html just vanished for /12/, and as a result https://www.postgresql.org/docs/current/recovery-config.html is a 404. I think that's unhelpful since we encourage people to use /current/ links.

The attached patch restores the recovery-config.html page with a short note explaining why it's gone and what to do instead. It's added to a new appendix "Obsolete or renamed features, settings and files".

I found it remarkably hard to find out what exactly made a "standby server" actually be a standby server in the docs so I have added a couple of cross-references that make the role of the standby.signal file much more discoverable from relevant locations.

I propose a policy that we preserve our <chapter> and <sect1> ids. We should move them to an "obsolete" section at the end, like the one I created here, and provide stubs for them instead of removing them. That'll help prevent us from breaking links on the wider web, in 3rd party documentation, etc.


0001-Link-the-old-recovery.conf-docs-chapter-to-the-new-d.patch (12K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Bruce Momjian
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
> Hi all
>
> I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for
> it were removed completely as well. That's largely sensible, but is confusing
> when users have upgraded and are trying to find out what happened, or how to
> configure equivalent functionality.

I don't see the logic in carrying doc stuff that we don't have anymore.

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

David G Johnston
On Wed, Nov 11, 2020 at 12:44 PM Bruce Momjian <[hidden email]> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
> Hi all
>
> I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for
> it were removed completely as well. That's largely sensible, but is confusing
> when users have upgraded and are trying to find out what happened, or how to
> configure equivalent functionality.

I don't see the logic in carrying doc stuff that we don't have anymore.


I do.  Saying why something went away has value.  For small stuff you have commit messages.  For user-facing documentation stuff that warranted its own page, having said page remain and describe the change seems worthwhile.

David J.
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Daniel Gustafsson
In reply to this post by Bruce Momjian
> On 11 Nov 2020, at 20:44, Bruce Momjian <[hidden email]> wrote:
> On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:

>> I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for
>> it were removed completely as well. That's largely sensible, but is confusing
>> when users have upgraded and are trying to find out what happened, or how to
>> configure equivalent functionality.
>
> I don't see the logic in carrying doc stuff that we don't have anymore.

Well, we do have that already in <tip>'s sprinkled across the docs where it
makes sense to help transitioning users, like this one in func.sgml:

    "Prior to PostgreSQL 12, it was possible to skip arbitrary text in the
    input string using non-letter or non-digit characters..."

It doesn't seem like a terrible idea to do a similar one for recovery.conf.

cheers ./daniel

Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Bruce Momjian
On Wed, Nov 11, 2020 at 08:59:40PM +0100, Daniel Gustafsson wrote:

> > On 11 Nov 2020, at 20:44, Bruce Momjian <[hidden email]> wrote:
> > On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
>
> >> I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for
> >> it were removed completely as well. That's largely sensible, but is confusing
> >> when users have upgraded and are trying to find out what happened, or how to
> >> configure equivalent functionality.
> >
> > I don't see the logic in carrying doc stuff that we don't have anymore.
>
> Well, we do have that already in <tip>'s sprinkled across the docs where it
> makes sense to help transitioning users, like this one in func.sgml:
>
>     "Prior to PostgreSQL 12, it was possible to skip arbitrary text in the
>     input string using non-letter or non-digit characters..."
>
> It doesn't seem like a terrible idea to do a similar one for recovery.conf.

I am fine with a tip.  The patch looked like it was creating a new
chapter for it.

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Daniel Gustafsson
> On 11 Nov 2020, at 21:01, Bruce Momjian <[hidden email]> wrote:
>
> On Wed, Nov 11, 2020 at 08:59:40PM +0100, Daniel Gustafsson wrote:
>>> On 11 Nov 2020, at 20:44, Bruce Momjian <[hidden email]> wrote:
>>> On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
>>
>>>> I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for
>>>> it were removed completely as well. That's largely sensible, but is confusing
>>>> when users have upgraded and are trying to find out what happened, or how to
>>>> configure equivalent functionality.
>>>
>>> I don't see the logic in carrying doc stuff that we don't have anymore.
>>
>> Well, we do have that already in <tip>'s sprinkled across the docs where it
>> makes sense to help transitioning users, like this one in func.sgml:
>>
>>    "Prior to PostgreSQL 12, it was possible to skip arbitrary text in the
>>    input string using non-letter or non-digit characters..."
>>
>> It doesn't seem like a terrible idea to do a similar one for recovery.conf.
>
> I am fine with a tip.  The patch looked like it was creating a new
> chapter for it.

I admittedly hadn't looked at the patch, but now that I have I agree with not
adding a separate "obsolete" topic for it.  I'd prefer to use tips within the
docs, they will also help guide users who search for recovery.conf and lands in
the tip which is next to the relevant updated documentation on the topic.

cheers ./daniel

Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Craig Ringer-5
In reply to this post by Bruce Momjian
On Thu, Nov 12, 2020 at 3:44 AM Bruce Momjian <[hidden email]> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
> Hi all
>
> I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for
> it were removed completely as well. That's largely sensible, but is confusing
> when users have upgraded and are trying to find out what happened, or how to
> configure equivalent functionality.

I don't see the logic in carrying doc stuff that we don't have anymore.

I explained why.

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' "

In general I think it's quite unpleasant for users to have docs sections just vanish. I strongly suggest that we enact a policy going forwards that any <chapter> or <sect1> removal should be accompanied by a redirect or stub that helps users find the new contents. It regularly annoys me when I'm trying to navigate around various versions of the docs and things just vanish.

Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Craig Ringer-5
In reply to this post by Bruce Momjian
On Thu, Nov 12, 2020 at 4:01 AM Bruce Momjian <[hidden email]> wrote:
On Wed, Nov 11, 2020 at 08:59:40PM +0100, Daniel Gustafsson wrote:
> > On 11 Nov 2020, at 20:44, Bruce Momjian <[hidden email]> wrote:
> > On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
>
> >> I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs for
> >> it were removed completely as well. That's largely sensible, but is confusing
> >> when users have upgraded and are trying to find out what happened, or how to
> >> configure equivalent functionality.
> >
> > I don't see the logic in carrying doc stuff that we don't have anymore.
>
> Well, we do have that already in <tip>'s sprinkled across the docs where it
> makes sense to help transitioning users, like this one in func.sgml:
>
>     "Prior to PostgreSQL 12, it was possible to skip arbitrary text in the
>     input string using non-letter or non-digit characters..."
>
> It doesn't seem like a terrible idea to do a similar one for recovery.conf.

I am fine with a tip.  The patch looked like it was creating a new
chapter for it.


It is. Or rather, an appendix right at the end to hold info on things we removed or renamed and where to find them now.

You can't AFAICS make docbook create a toplevel linkable file for a <tip> . A <tip> won't un-break https://www.postgresql.org/docs/current/recovery-config.html or make help people who visit https://www.postgresql.org/docs/11/recovery-config.html figure out what's going on if they're using pg12 and there's no link to version 12 in the nav section. A <tip> won't add index entries for renamed settings, so someone looking up "standby_mode" can find out that we've switched to a file called "standby.signal" instead.

Pretend you're a user who has upgraded from pg 11. You're looking at the Pg 12 docs. How long does it take you to find out how to make a server into a standby now? It took me longer than I would've expected...


Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Bruce Momjian
In reply to this post by Craig Ringer-5
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.
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.

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Stephen Frost
Greetings,

* Bruce Momjian ([hidden email]) 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 (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Stephen Frost
Greetings,

* Stephen Frost ([hidden email]) wrote:

> * Bruce Momjian ([hidden email]) 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

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Bruce Momjian
In reply to this post by Stephen Frost
On Thu, Nov 12, 2020 at 09:47:42AM -0500, Stephen Frost wrote:

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

Yes, I am thinking someone could go back and add redirects for previous
renames too.  It would be interesting also to scrape the web logs for
404 errors to see which renames cause the most failures and do those
first.

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Craig Ringer-5
In reply to this post by Stephen Frost
On Thu, Nov 12, 2020 at 11:25 PM Stephen Frost <[hidden email]> 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...
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Craig Ringer-5
On Fri, Nov 13, 2020 at 11:31 AM Craig Ringer <[hidden email]> wrote:

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

Also, while I'm at it, note that a search on common search engines for "postgres standby" takes you to (an old version of) the hot standby docs. Follow the link to the current docs. Then try to work out from there what exactly makes a server in "archive recovery" or "standby mode".


We need some <link ....> terms on "archive recovery" and "standby mode" there, and probably other places.

I have a draft patch that adds them and various related index cross-referencing in my tree to submit after the recovery.conf docs patch. Let me know if you think that might be worthwhile, 'cos I won't invest time in it if it's going to get reflexively blocked too.
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Bruce Momjian
In reply to this post by Craig Ringer-5
On Fri, Nov 13, 2020 at 11:31:24AM +0800, Craig Ringer wrote:
> 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...

Because at a certain point the number of _old_ names in the docs
obscures exactly how to operate the current software.  We have tried
keeping stuff around, and we are very bad at removing stuff.

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Isaac Morland
In reply to this post by Craig Ringer-5
On Thu, 12 Nov 2020 at 22:31, Craig Ringer <[hidden email]> wrote:
 
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.

This sounds very reasonable to me. I would add that while I am by no means an expert in Postgres, although I do know a few things, I will state that it is my professional opinion as a Web person that pages should not simply disappear from formal documentation without some sort of indication of what happened. There are lots of ways to accomplish an indication but for https://www.postgresql.org/docs/current/recovery-config.html or other pages to just disappear is definitely wrong.

Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Bruce Momjian
In reply to this post by Craig Ringer-5
On Fri, Nov 13, 2020 at 11:37:16AM +0800, Craig Ringer wrote:
> I have a draft patch that adds them and various related index cross-referencing
> in my tree to submit after the recovery.conf docs patch. Let me know if you
> think that might be worthwhile, 'cos I won't invest time in it if it's going to
> get reflexively blocked too.

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.

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Isaac Morland
In reply to this post by Bruce Momjian
On Thu, 12 Nov 2020 at 22:40, Bruce Momjian <[hidden email]> wrote:

Because at a certain point the number of _old_ names in the docs
obscures exactly how to operate the current software.  We have tried
keeping stuff around, and we are very bad at removing stuff.

This is a good point, but does not attempt to explain why pages should disappear entirely from /docs/current/. As I said in my previous comment, there are lots of ways of doing this right. For example, we could have pages that would disappear instead be replaced by a short page that explains the page is removed and points to the current documentation of the equivalent or replacement features; these hypothetical "useful 404" (or, more correctly, "useful 410") pages don't even necessarily have to be listed in the table of contents. In fact, serving them with a 410 HTTP status code would be a reasonable thing to do.
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Bruce Momjian
In reply to this post by Bruce Momjian
On Thu, Nov 12, 2020 at 10:41:49PM -0500, Bruce Momjian wrote:

> On Fri, Nov 13, 2020 at 11:37:16AM +0800, Craig Ringer wrote:
> > I have a draft patch that adds them and various related index cross-referencing
> > in my tree to submit after the recovery.conf docs patch. Let me know if you
> > think that might be worthwhile, 'cos I won't invest time in it if it's going to
> > get reflexively blocked too.
>
> 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.

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

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Craig Ringer-5
On Fri, Nov 13, 2020 at 11:50 AM Bruce Momjian <[hidden email]> 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.
123