Dear Scala contributors,
The Scala documentation website is where both newcomers and experienced Scala developers expect to find answers to any Scala question they might have. Over the years, and especially with the recent release of Scala 3, a lot of documentation content has been scattered at various places. This thread presents our Scala Center project for updating and improving the current state of the documentation.
Since the beginning of the development of Dotty (which just became Scala 3), its documentation has been hosted at https://dotty.epfl.ch. The Scala documentation website progressively incorporated content related to Scala 3, and we are now in a situation where there is a high level of overlap between the content of the Scala 3 documentation on https://docs.scala-lang.org, and https://dotty.epfl.ch.
In parallel, unrelated to Scala 3, the content on https://docs.scala-lang.org has grown organically over the years. As a result, the website contains a lot of important information (like how to publish a library), but that information is a hard to find out when browsing the site. Furthermore, as recently raised in Next steps in further improving community experience after the awesome Scala 3 release?, the instructions for getting started are still too cumbersome (this point is also supported by SCP-26).
The goal of the Scala Center is to improve the current state of the Scala documentation website, by centralizing the content at a single place, by simplifying the organization of the documentation to make things easy to find, and by double-checking that the content is up to date.
- (done) Review the content of the Scala 3 book to make sure its content is up to date with the recent developments of the language. Related pull requests: #2062 #2073 #2076 #2079 #2088.
- (done) Merge the content of https://dotty.epfl.ch into https://docs.scala-lang.org, so that the content is at one place only.
This will include removing duplicated set up instructions, and creating new pages on docs.scala-lang.org to host the Scala 3 reference documentation. After that, https://dotty.epfl.ch will be archived (read-only, with a banner pointing to https://docs.scala-lang.org). Related pull requests: #2112, #13094, #2137, #2136.
- (in progress) Overhaul the structure of the documentation. This work requires some brainstorming, and we are happy to hear your suggestions in this thread. We will post an update with a plan, open to discussion, as soon as it is ready. Delivery estimate: November 2021.