On Fri, Nov 13, 2020 at 10:42 AM Bruce Momjian <bruce@momjian.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:
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.