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