HELP topics are/will be generated from the Knowledge Base, so once any changes are documented, they will appear in the HELP.

That's a weird chain of events. Shouldn't help tables be brought up-to-date with the release, upon upgrade, not after it?

Probably, but that's basically never happened. For much of MariaDB's history, the HELP tables contained the contents as imported from MySQL. Generating them from the KB has the benefit of documentation needing to be updated in one place only.

The documentation on the KB could be updated in advance, which is probably more doable, but also almost never happens.

First thing that comes to mind is that it should be exactly the opposite (if doable of course) – that is, the help topics to be updated before a release, and then the KB topics to be generated from them after the release. It would keep the benefit of a single update and maintain the natural timing.

Can it be done this way? Maybe not right now, but in general?

Well, in theory, but it's very far from what we have, and I don't see the point. The HELP contents are populated by a bunch of SQL queries generated from the KB. It is (or at least was) done this way around in MySQL as well. The SQL contains less information, no hypertext etc, so information will have to either be added later for the KB, or unnecessarily stored and stripped for display in the SQL, in order to do it this way. Amending and formatting a query is more painful than editing a wiki, so this just adds a barrier upfront that will reduce the likelihood of early documentation.

If the intention is to have up-to-date HELP contents, then the developer developing the feature could edit the KB in advance, and it will appear in the next version of the HELP. Ideally this would appear in the same version. This is a script run by me at present, so its doable right now with enough notice, but could be automated, and likely will be at some stage.

Ultimately this comes down to including documentation in the workflow. Doing the documentation, or at least flagging a documentation issue, neither of which happen reliably right now. I'd be happy just seeing a documentation MDEV for each relevant change.

Well, in theory, but it's very far from what we have, and I don't see the point. The HELP contents are populated by a bunch of SQL queries generated from the KB.

I don't think there is any point in having a help within the server, when this help doesn't correspond the server version it is in. True, we didn't pay much attention to it so far, but we should start sooner or later, and it seems very obvious that it should either be accurate or shouldn't exist (I personally would be quite happy with the latter option). It is one thing when the help is missing new topics – it is unfortunate but not very problematic; but when something changes and the help becomes straight wrong – that's a problem.

Maybe the help within the server should be converted from the full text topics to a simple name => link pair, pointing to corresponding pages in the KB (links are already there)? Nothing works without the internet these days anyway, so I don't think it's such a huge loss for the users. It is pity if the KB is changed next day after the release, but the help within the server remains wrong until users upgrade next time.

It is (or at least was) done this way around in MySQL as well.

I don't know details of how it is/was done, but it may have something to do with MySQL documentation actually being a part of the workflow, as you pointed at the end? they update documentation with each closed item, so by the time of a release the documentation (the new version) is up-to-date and can be used for generation.

If the intention is to have up-to-date HELP contents, then the developer developing the feature could edit the KB in advance, and it will appear in the next version of the HELP.

I don't believe it's a great idea to put this responsibility in general on developers. Small amends maybe, but when it comes to bigger changes in the KB, it requires a professional, as everything else. Which is probably another reason for not having the documentation within the server code.

Ultimately this comes down to including documentation in the workflow. Doing the documentation, or at least flagging a documentation issue, neither of which happen reliably right now. I'd be happy just seeing a documentation MDEV for each relevant change.

True, but it won't change much for the help or for timely updates unless we also make such an MDEV a blocker for the release. It isn't impossible to start creating MDEVs, but do you think the documentation will be able to keep up without holding off the releases?

At the end, both the KB https://mariadb.com/kb/en/alter-user/ and the help topic still say

The global SUPER privilege is also required if the read_only system variable is enabled