Scala documentation, web sites: What should be improved?

Documentation
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