Scala documentation, web sites: What should be improved?

Documentation
21

One thing that would help a lot would be more applied examples with documentation; often we define things in very generic and mathsy terms, and leave the “and here’s when you’d use that” up to the reader. I think generally more examples using some business modelling would help a lot with onboarding; applied examples, instead of simply defining things correctly. E.g. instead of FooBar, maybe User/Database or CreditCard/Transaction and sort of lower the abstraction level. It doesn’t have to replace the mathematical rigour, but learning via ~3 examples really allows people’s pattern recognition to kick in vs trying to learn from first principles.

6 Likes
22

Some small ways would be:

  1. Add an issue template for documentation for “New issue” in GitHub · Where software is built
    This would make it easier to document issues with the docs, given they are usually spotted in the middle of doing something else, and it’s not always possible to fix it directly
    It would also mean the issue directly gets tagged correctly, instead of someone needing to come assign a label to it
  2. Add a “issue with this page” button to the overlay of Reference pages (which links to the above)
  3. Add an edit button to the overlay of Reference pages
    There is one above the title, but it’s easy to miss, since usually mistakes are in the middle of pages, and you usually skim the title, since you knew where you were going
  4. When switching version, remember which page I’m on
    Example: From Match Types, changing version to 3.3 LTS brings me to Scala 3 and not to Match Types
3 Likes
23

This is a list from a group of people (including me). I am posting it on their behalf.

  1. SAM documentation. It needs some love. Also, right now the first google result has a NSFW image just when you open the link: Explaining Scala SAM type | Abitrarily Idiosyncratic Randomness . The first link should be the Scala docs. As final addition, to get this issue resolved: SAM doesn't work with polymorphic functions · Issue #6904 · scala/scala3 · GitHub
  2. Macros and Metaprograming: The docs are really hard. All the info is actually there, but they are extreamly cryptic and I experience the effect of I see words, I understand meaning of each word, yet I do not understand all together. Maybe here the community would benefit of the huge literature about macros and meta programing done by Mateusz Kubuszok.

We support the already mention improvements. To name a few:

  • Compiler flags for Scala 3 (not the migration guide, the actual flags, what they do and their values)
  • Aligning Scala docs in Scala site with Scala 3 reference and change experimental into non-experimental when the features are stable.
6 Likes
24

I don’t know if the website infrastructure is in scope, but I just filed this issue and it’s a pretty big pain point for some parts of the world: Scala websites have significant geographic latency · Issue #1885 · scala/scala-lang · GitHub

25

Are there plans to merge mdoc and scaladoc? Maintaining two tools with overlapping functionality seems redundant.

26

The overlap is there for sure, but the only thing we were thinking about is having a common snippet compiler similar to REPL. Nobody looked into that though since it’s not a very high priority

1 Like
27

I wanted to see what everyone else said first, but now that some time has passed, here are some ideas that have come up over the years that seem important to me:

10 Likes
28

I’d like to see the entire language reference have compiler-checked snippets. But that also requires dusting off the snippet compiler and Scastie integration.

7 Likes
29

I second this motion.

As for me personally, I’d like to see more completeness around the documentation of macros/inline (metaprogramming). It would help both humans and agents using those features, which have proven to me to be one of the greatest perks of using scala 3

2 Likes
30

I should add that The Rust Book is quite exemplary in that regard and we should strive to have the same quality. Right now, the tools we have at our disposal need some loving care to accomplish that. It’d help humans, agents, and compiler maintainers equally.

4 Likes
31

Scaladoc issues,

  1. Too much empty space, both in sidebars and central content.
  2. Companions objects on different lines than corresponding classes/traits. Difficult to quickly understand which classes and traits do have companion objects. Find them polluting the hierarchy and taking up the space. Don’t feel confident if it’s a companion object at all or not, should read the name properly to understand it. Is it even considered a companion object if it’s, e.g. in a different source file?
  3. I can’t scroll the whole page to access all information, but have to focus on different parts of the page and scroll there.
  4. Big and visible search bar, easy to click, is now hidden behind a tiny icon in the upper right corner.
  5. Old version shows me the root cats package documentation immediately, on the new one, I need to click it first, which may not be obvious for everyone.
  6. 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”.

I’m not a professional UX person, just noticed an inner resistance to use Scala 3’s Scaladoc comparing to the old one, and tried to analyze where the resistance is coming from.

2 Likes
32

something big I forgot to include on my list before:

1 Like
33

Thanks to everyone who has made suggestions! I’m now writing a blog post summarizing the feedback and laying out what we intend to work on.

As an aside, I hadn’t previously noticed this thread from 2021: Scala documentation website roadmap — I’ll see what’s there that we might able to use.

2 Likes
34

I’m going to try to respond to every suggestion that has been made in this thread.

In a subsequent post, I’ll show what we consider to be the highest priority items.

In this post, I’m replying to suggestions that seem either of out of scope, or too ambitious for the people and the amount of funding we currently have.

Anything below could nonetheless be tackled by volunteers, or could perhaps be addressed in a future round of funding.

Some of these responses will be disappointing to many, and I am sorry. We wish we could do more.

Update Scala 3 Book

  • Update The Scala 3 Book (donated to the Scala web site by Alvin Alexander) for new Scala versions and features
  • from: @SethTisue
  • link: Introduction | Scala 3 — Book | Scala Documentation
  • my response (to myself): I wish we had the resources for this, but I fear that we simply don’t, or not this year anyway. The book originally came in as volunteer effort; if volunteers are able to update it, the help is welcome. I believe it’s a higher priority for us to provide reference documentation, leaving books to the book authors.

Metaprogramming documentation

  • @datalin: “I would really appreciate thorough documentation and guides on metaprogramming and macros with helpful examples”
    • @ragnar: make metaprogramming docs link to dotty-macro-examples repo
    • @dagmendez: “The docs are really hard. All the info is actually there, but they are extremely cryptic”
    • @NovaMage: “I’d like to see more completeness around the documentation of macros/inline (metaprogramming)”
    • my response: Sadly, while I agree the metaprogramming docs need work in many areas, it seems unlikely to me that we will have sufficient resources under the Sovereign funding to focus on this in 2026. I’m very aware this might be the most disappointing single response in this list. Is someone interested in funding this? Or perhaps we could try to ask for it in our 2027 Sovereign application?

Barriers for entry to doc contributors

  • @AMatveev: “recommend vs code previewer which allows to write documentation without needing to install and learn documentation build tool”
    • my response: generally this doesn’t seem like much of a barrier for entry to me; I use a Markdown viewer as a first pass at how something will look. also the website repos have up-to-date info on how to run the build and it’s normally just bundle install followed by bundle exec jekyll serve. and not sure if VS Code Previewer would really help with Scaladoc?

Engage a technical writer

  • @AMatveev: “assign a technical writer to help fix typographical errors in incoming merge requests”
    • my response: we don’t have a technical writer, per se. some typos get caught during review, others can be fixed later when noticed. If anyone’s employer would be able to donate some of a technical’s writer time, that would be greatly appreciated.

Engage a UI/UX designer

  • @JD557: “can we get a UI/UX designer to work on the Scaladoc style”
    • my response: "my sense is that with the people and resources we have for 2026, we’re better off focusing on content and on whatever visual improvements we can make ourselves without engaging a designer, though we would certainly consider a designer’s pull requests if someone wants to donate their services. once we had a company donate a designer’s time; that would be extremely welcome if it happened again

Issues with pre-3.9 docs

  • @kubukoz/@bishabosha/@WojciechMazur: issues with Scala 3.4-3.6 docs, fixed since 3.7
    • my response: With the Sovereign funding, I would prefer to focus on Scala 3.9 LTS and above. (Wojciech said he might work on the old docs anyway.)

Scala-cli help

  • @som-snytt: improve scala-cli help
    • my response: we’re focusing more on language doc, API doc, and website; please open a ticket in the scala-cli repo

Scaladoc not viewable without web server

  • @markehammons
    • “to autoboot a webserver with the docs you want to view, in the case you have the docs pre downloaded”
    • my response: while, this would be welcome as an external contribution, but I think it’s primarily an IDE function and making it available outside of the IDE context would only server a limited audience
    • also @charpov notes maybe this isn’t a problem with the latest doc?
    • if you still experience it, please open a ticket in the scala/scala3 repo

Geographic latency of Scala websites

Merge mdoc and scaladoc

  • @matejcerny: “Are there plans to merge mdoc and scaladoc? Maintaining two tools with overlapping functionality seems redundant.”
  • my response: this is interesting, but in order to be actionable, we’d need specifics. mdoc itself is out of scope for the Sovereign funding. Scaladoc improvements might be in scope, though. Are there specific mdoc features that are missing from Scaladoc and you would especially like to see added?
  • see also @tgodzik’s response
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
36

there used be updates in the Source Compatibility page but seems it wasnt part of the release procedure to update - but also that is really talking about only the import scala.language.`3.x` imports and what they change. (however its a pretty good proxy, e.g. -source:3.6 will turn off the syntax for Named Tuples)

37

Something in that direction is on my TODO list for the SIP page. I’ve compiled a table using LLM wizardry from the scala-lang.org commit history and can share it, if you need it.

38

It’s fine to have this information appear in more than one place, but it’s best if we have a single source of truth.

39

It is an argument which is very difficult to refute :wink:

I can only talk about my experience:
We had 3 attempts to organize documentation as code:

  • dita-ot - it was a bad idea at the begining )))
  • sphinx - I did not see any problem at the start …
  • markdown - It really has began to work

I can’t say what exactly became the decisive factor.

Most likely the technical writers do main works. It’s really very convenient when you can just dictate improvements by voice and they will appear in the documentation :wink:

But I am personally very happy to work with markdown + vscode without any build tool. Markdown is very common and has light learning curve. It is much easier for me to start working even after several months of other work. Documentation is not my duty so any complexity can stop me.

But after all it is very difficult to say what really is a decisive factor.

1 Like
40

I don’t recall any specific feature, but I would really like to see simplifications in the Scaladoc settings. It was quite painful to migrate from mdoc to Scaladoc, some things are configured via the scalac options (which is very strange, if you ask me), and others have to be hacked. Here is the source for a really simple site. An example repo linked to the documentation would be very helpful.

Scala/Kotlin interoperability would be also great, there are not that many resources about this topic. (I personally worked on a project which included Kotlin dependencies and vice versa, we had Kotlin projects depending on Scala libs)