Scala documentation website roadmap

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.

Problem

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.

Solution

  • (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.
  • (todo) 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.
16 Likes

Any chance we could try to avoid the type of document separation that exists in scala<3:

IMHO, there is really no need to have: ‘language spec’, ‘overviews’, ‘scala book’, and ‘style guide’.
The first 3 should be merged into one comprehensive scala book (overviews are just an introductory sections to bigger chapters, language spec is just an addendum to a chapter) this way there is nothing hiding in the spec (which currently hides a lot of surprising details, and is generally written in a less friendly manner. Maybe because it is only meant to be read by “professionals”). ‘style guide’, is just another chapter.

Another thing is that ‘tour of scala’, should be added to ‘getting started’ IMO, but that’s less critical.

This is a very real issue with scala in my opinion and although there is an amazing amount of quality content, I really hope it could be better organized (scala 3 opens the opportunity to approach this early).

Thank you

4 Likes

The spec really shouldn’t be relegated to an addendum to a chapter of a book I think.

2 Likes

I agree that there are too many types of documents, with a significant amount of overlap between them (e.g., tour, “book”, and overviews are very similar).

On the other hand, I believe that some pages (e.g. Implementing Custom Collections) are quite specific, and I do think they should be aside from the “main” documentation.

So, finding the right balance is not easy!

While the documentation definitely needs a lot of reorganization and rationalization, I disagree with the notion that it can or should be squished down to just one or two documents.

There are different use cases, different needs, and different audiences. The spec is a technical document – extremely precise, extremely detailed, but inappropriate for casual use. That’s entirely correct: good languages need precise specs, but those specs aren’t something that most folks should be using. I think I’ve used the spec fewer than ten times in the dozen years I’ve been using the language – I’m not the audience.

Similarly, a good tutorial is not the same thing as a reference manual. We have a good reference manual, but I usually steer people away from it when they are starting out. Reference manuals are rarely good pedagogy, and pedagogy is what matters when someone is learning a language.

There’s a lot of room for improvement. But IMO there are at least three different purposes here, and those are unlikely to be well-served by a single document.

6 Likes

I agree that having three different documents makes sense from the standpoint of style and consistency of detail.

As fewer of these documents are existing in dead-tree format, one way to reduce the lack of visibility and confusion may be to make extensive use of references & hyperlinks between these layers of documentation.

For example, in addition to a [Next](...) link at the bottom of a page in the tutorial, there could be a link to the relevant section in the reference manual and some thing like this:

For additional details, see The Big Reference Book, Chapter 3, Section 2, which can be found [here](...)

The sections of the reference book could likewise have a link at the end of each pointing to the appropriate sections of the spec for the bits referenced in that section.

Presumably when these are being written, the authors are referencing at least the next most detailed layer of documentation, so the links may already be close to hand in the authors’ notes (even if they don’t currently make it into the final text).

2 Likes

I really disagree regarding the reference (scala book) vs spec, the part about having some quick separate tutorial makes sense, I didn’t mean that all tutorials will be in the reference.

When someone actually writes some code, even very basic scala programs, they very quickly they need to understand parts that are only in the spec, they may not realize it, because of… stackoverflow, google, random github issues search, copy-paste methods. Those do get people moving forward, but we can do better. (Just to give some context, I am teaching principles of programming languages courses to undergraduates).

The ‘quick guide with missing details’ approach is very problematic, details matter. I’m not saying that everything should be written as a tutorial, but every topic should have a guide/examples and accurate full details in the same place, if someone doesn’t want to look at the syntax tree or the precise inference algorithm he/she will skip but it should be easy to find and written in a manner that expects that people will be reading it and not just compiler experts (and I don’t believe the ‘compiler experts’ or the ‘casual users’ are going to find any of this harder to read, even experts need the occasional friendly example).

Also note, I’ve learned, forgot, and relearned scala a few times over the years, really, the experience is fresh to me, you can’t write code in scala without using stackoverflow answers that (inaccurately) dumb down parts that are only in the language spec. I hope this could be improved, scala is complicated, I don’t see the point of hiding details in a separate spec.

Given everything is public and you have a strong position on how this ought work, why don’t you give your idea a quick stab and flesh out a mockup. Don’t do the entire thing. Just demonstrate your particular perspective with enough fleshed out it conveys what you are attempting to describe.

It makes it much easier to be open to a “new idea” when the provider/purveyor of the new idea has demonstrated skin-in-the-game by investing time in a partial prototype implementation.