The way the various documentation websites are generated is not documented

[julienrf]

I think there is a general lack of clarity about how the various docs are generated.

As far as I understand, we have:

• https://scala-lang.org/api/3.x (which is generated by VirtusLab publishing some files to an EPFL-owned server)
• https://docs.scala-lang.org/scala3/reference (which is generated by EPFL, by pulling the content of https://github.com/lampepfl/scala3-reference-docs, which is itself generated automatically from the content on this repository on branch language-reference-stable)
• https://dotty.epfl.ch (nightly documentation, generated by a GitHub action here I guess?)

Correct me if I am wrong, and please document those things here (in CONTRIBUTING.md?), and explain the policies regarding what goes into what branch (if I want to fix something in the documentation, should I target main or language-reference-stable?).

Last, make sure the release procedure takes all those forms of documentation into account (currently, it seems only the API documentation is updated during the release process, but you should also merge the content of the main branch to language-reference-stable before the release)

Originally posted by @julienrf in #16201 (comment)

To add to the original issue, I would like to mention that a GitHub action failed after we merged a contribution (#16202) to language-reference-stable, and we don’t understand the purpose of this action. I believe better documentation would help us deal with such kind of issues in the future.