Re: Add docs stub for recovery.conf

On Sun, Nov 15, 2020 at 1:49 PM David G. Johnston <
david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

> On Fri, Nov 13, 2020 at 10:42 AM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
>
>> I think the big problem, and I have seen this repeatedly, is showing up
>> with a patch without discussing whether people actually want the
>> feature. I know it is a doc issue, but our TODO list has the order as:
>>
>> Desirability -> Design -> Implement -> Test -> Review -> Commit
>
>
>> and there is a reason for that. When you appear with a patch, you are
>> already far down the steps, and you have to back up to explain why it is
>> useful.
>>
>
> That process is designed to prevent people from being exposed to wasted
> effort and hard feelings. The choice to follow it individually, instead of
> collectively, doesn't diminish the value of the end result.
>

Frankly, it's also kind of a catch-22. Because often proposals for changes
or discussion get ignored until there's a patch, or the response is along
the lines of "show us a patch so we can try it and get a solid idea of what
this will do."

For major engineering changes, yes, discuss first. For small stuff, if you
don't want to get ignored, open with a patch.

On the point of renaming, my suggestion would be to have the documentation
> directory provide a file of all renaming for which redirects should be
> performed. pgweb would source that file and actually establish the
> redirects on the main website. Comments in the file can describe to a
> curious user why the name change was needed. Though that honestly seems a
> bit overkill; for rename, the content as a whole still exists and a comment
> therein can talk about the renaming. Users of the public website would
> still get the benefit of redirects, and there isn't any practical reason
> for people building documentation from source to want to establish such
> redirects even if they were provided the data in the form of the
> aforementioned file.
>

Agreed, there's no need to keep heading redirects in the source-built docs.
So if we're happy to maintain that on the website, in a way that makes
/current/ links work *and* following links from a /11/ docs page that has
vanished in pg12 to the right new place via the version navigation links,
that's sufficient for topic-heading renames.

We should, however, carry information about removals and renames in the
source-built docs to the extent that we have appropriate "see also" index
entries and useful information somewhere in the docs for people who are
upgrading. It just doesn't have to retain the same subject heading.