Re: Add docs stub for recovery.conf

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.

I generally agree with Craig's proposed solution here. It doesn't add any
cognitive load to new users as they will not see the obsolete features
appendix in the normal course of their reading.

To the particular point regarding renaming features - this situation is not
an instance of a rename but rather a feature removal. To blindly apply the
reasoning and decision made for renaming to removal is not reasonable.
From that observation (and the commentary below) extends the conclusion
that this appendix shouldn't include renaming.

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.

I believe there is probably room for more discussion regarding the value of
providing a limited view of history in the publicly facing documentation
but that seems outside the scope of this patch.

David J.