I also noticed that if I install a platform manually in {directories.user}/hardware/STMicroelectronics/stm32/..., while already having a installation via the Board Manager in {directories.data}/packages/STMicroelectronics/hardware/stm32/2.8.1/..., the one in the user directory takes precedence for what is seen in the Arduino IDE.

Example:

image

The problem is however, that I had a new version in {directories.user}/hardware/STMicroelectronics/stm32/... with new board variants, but I could not see those in the Board part number: ... menu as expected.

Is this a separate bug? In that it is possible to install a platform manually, and it is seen in the menu, but the actual new additions to the manual installation are not shown?

Also it might be good to mention in these docs what happens if you have the same VENDOR_NAME and ARCHITECTURE in these data and user directory?

Is this a separate bug? In that it is possible to install a platform manually, and it is seen in the menu, but the actual new additions to the manual installation are not shown?

Currently, if there are two matching platforms the one installed in the sketchbook should take precedence... but since you're not able to see the new board definitions there could be a regression, I'll check this out.
To avoid confusion, during the development of a platform, we use the "trick" to slightly rename the vendor installed in the sketchbook so instead of:

{directories.user}/hardware/STMicroelectronics/stm32/...

we use for example:

{directories.user}/hardware/STMicroelectronics-dev/stm32/...

This way there is no confusion and both platforms (the original and the "dev") are visible in the IDE.

Also it might be good to mention in these docs what happens if you have the same VENDOR_NAME and ARCHITECTURE in these data and user directory?

Yes good point.

This way there is no confusion and both platforms (the original and the "dev") are visible in the IDE.

This was not the case for me. I only saw the one as you see in the picture above.

except I saw no mention of what happens there are matching VENDOR+ARCHITECTURE namings in the data and user directory

I checked, and the Arduino CLI has a bug/regression. The expected behavior is not happening (the platform installed in the sketchbook should take priority over the one installed via Board Manager if they match VENDOR+ARCHITECTURE).

I'm going to open a new issue about this, I'll add the note in the documentation after the bug is fixed.
In the meantime, I'm merging this one.