Two different versions of the Reference exist

[Sporarum]

https://docs.scala-lang.org/scala3/reference/
https://www.scala-lang.org/api/3.x/docs/

There is not a redirect from one to the other, and seemingly the only difference is the "Scala 3" vs "Scala 3 Reference", as well as the version toggle
(and a dead link, see #25152)

[WojciechMazur]

This is expected (with exception of linked #25152 issue)

https://docs.scala-lang.org/scala3/reference/ hosts only language reference of last stable version, based on https://github.com/scala/scala3/tree/language-reference-stable ensuring links are stable

https://www.scala-lang.org/api/3.x/docs/ hosts mainly an API generated from Scala standard library (both Scala 2 and 3), is versioned per stable release, which can change. There are no guarantees regarding link stability between two API versions and the layout, see for example difference:

• in 3.3 LTS: https://scala-lang.org/api/3.3_LTS/docs/docs/reference/new-types/match-types.html
• in 3.8: https://scala-lang.org/api/3.x/docs/new-types/match-types.html

Refering to thread from contributors.scala-lang.org, this extra docs segment causes an issue when we switch between docs versions - given path does not exist in other version so we end up in the docs root.

Starting with ~3.3 as a sideeffect of other changes it started to also produce reference docs for this single version. It was kept since currently it's the only way to have a Scala version specific documentation, e.g. different for 3.3 LTS and 3.8 Next which is useful

[Sporarum]

I see

This system seems very flawed to me:

1. I had no idea there were two reference pages, and visually nothing hinted at that
2. Search engines similarly have no idea, and will probably show one at random
   (For example wikis have a lot of issues migrating because of SEO: the old wiki gets recommended even years after it is obsolete)
3. It feels like links breaking for the "unstable" reference is still bad ?
4. Being able to change version would also be useful on the stable reference (and every other piece of docs)

So here is my recommendation:

1. (preferred) Have a single reference page
   1. Every link is stable (this should really be true of every website !)
   2. Versioning (with precise versions, but also "latest", "latest LTS", "3.3.x", etc)
   3. The stable reference are deprecated, but redirect to the versioned reference, at the latest version
2. Keep two different pages:
   1. Have a clear banner at the top of the unstable one explaining the system, and encouraging people to link the other one
   2. Provide some sort of "permalink" button
   3. Have a link to the versioned reference from the stable reference