Scala documentation, web sites: What should be improved?

Documentation
35

And here’s the rest of the suggestions (including internally generated ones), the ones that we do hope to work on in 2026.

We cannot promise to address everything in this post, but in rough descending order of importance, here’s what we most hope to work on under the Sovereign funding.

General suggestions

(meta) Improve issue reporting for documentation problems

  • from: @Sporarum
  • link: Scala documentation, web sites: What should be improved? - #22 by Sporarum
  • “Add an issue template for documentation for “New issue”” in scala/scala3 repo
  • “Add a “issue with this page” button to the overlay of Reference pages” (which links to above template)
  • “Add an edit button to the overlay of Reference pages”
  • “When switching version, remember which page I’m on”
  • my response: yeah, we should do all this

Reduce backlog of unhandled PRs and issues on website repos

  • from: @SethTisue
  • I consider this very high importance, because volunteers will be reluctant to contribute if they see that past contributions haven’t been responded to.

Fix classes that have zero documentation

  • from: @charpov
  • link: Scala documentation, web sites: What should be improved? - #12 by charpov
  • “I regularly end up looking at classes with zero documentation. Often (but not always), they are used for implicit conversions”
  • my response: this was in our own initial proposal to Sovereign and we will be working on it
  • “It’s unfortunate that these classes need to be public and I wish there were a way to hide them from the documentation”
  • my response: regardless, we should at least say something about why the class exists and what it does, even if the upshot is “don’t worry about it, you won’t normally run into this”

Do a sweep through all stdlib Scaladoc

  • This was in the original proposal we submitted to Sovereign and work is underway

Add automated checking of code examples

Include applied examples in documentation

Specific topic areas

Document what Scala versions language features debuted or progressed in

  • from: @kitbellew
  • link: Scala documentation, web sites: What should be improved? - #14 by kitbellew
  • “every feature ideally mentioned along with the version(s) of scala it appeared in”
  • @dagmendez adds: “change experimental into non-experimental when the features are stable” – make sure this is accurate everywhere
  • my response: I think we should make it a high priority to make a new page that shows all Scala 3 minor versions and what features became experimental or preview or final in that version. This page would be one-stop shopping to see the language evolving. I also agree it would be desirable to include this same information on the pages documenting individual features; we’ve let what information exists fall out of date

Write a new guide on Scala/Java interoperability

  • from: @SethTisue
  • The first version wouldn’t need to be long and comprehensive; it would be valuable even to have something fairly short, to start with, that briefly covers the main things people usually ask about.

Document compiler options

Document the REPL

  • from: @SethTisue
  • There is old doc at https://docs.scala-lang.org/overviews/repl/overview.html but it isn’t even very up to date for Scala 2, let alone Scala 3
  • A first revised version wouldn’t need to be long and comprehensive; it would be valuable even to have something fairly short, to start with, that briefly covers the main things people usually ask about.

Update language tour for Scala 3

Reorganize docs to center Scala 3 rather than centering 2->3 migration

Remedy features missing from reference documentation

Be consistent where features are documented

Update language specification

  • from: @SethTisue
  • We hope to engage a member of the compiler team to do at least some work on this in 2026. Probably not enough to fully update the spec, but enough to make progress on some especially important items.

Add links from beginner pages to in-depth docs

Add links from reference docs to language spec

Adopt Martin’s “common Scala style” proposal in examples

Make some improvements to structure and look of Scaladoc pages

  • from: @JD557
  • link: Scala documentation, web sites: What should be improved? - #6 by JD557
  • from: @igor-ramazanov
  • link: Scala documentation, web sites: What should be improved? - #31 by igor-ramazanov
  • from: @AMatveev
  • link: Scala documentation, web sites: What should be improved? - #11 by AMatveev
  • issues:
    • “lack of colors in text heavy pages”
    • “having some indicator near external links could also help”
    • improve design of “left-side pane… There’s just so much irrelevant information there”
    • “Companions objects on different lines than corresponding classes/traits. Difficult to quickly understand which classes and traits do have companion objects”
    • “I can’t scroll the whole page to access all information, but have to focus on different parts of the page and scroll there.”
    • “Big and visible search bar, easy to click, is now hidden behind a tiny icon in the upper right corner”
    • “[Scala 2] shows me the root package documentation immediately, on the new one, I need to click it first”
    • “Old version reflects the opened element in the browser’s address bar. In the new I need to right-click on an element and then “copy link””
    • “There is absence of navigation between types and its extensions in scala doc. We actually have to use text search to see available methods”
  • my response: we’d have to decide which of these to tackle, but surely we should tackle at least some. Improvements in this area are especially ripe for volunteer effort.

Improve Scala 3 syntax highlight on websites

4 Likes