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.
5 Likes
Some small ways would be:
- 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 - Add a “issue with this page” button to the overlay of Reference pages (which links to the above)
- 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 - 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
2 Likes
This is a list from a group of people (including me). I am posting it on their behalf.
- 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
- 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.
5 Likes
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
1 Like
Are there plans to merge mdoc and scaladoc? Maintaining two tools with overlapping functionality seems redundant.
1 Like
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
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:
- Clear the backlog of unhandled PRs on Pull requests · scala/docs.scala-lang · GitHub
- Use an up-to-date Scala 3 syntax highlighter on the websites (either bring Rouge up to date, or switch to treesitter or Linguist, see Switch to treesitter or linguist for syntax highlighting? · Issue #1833 · scala/scala-lang · GitHub)
- Document Scala 3 and Scala 2 compiler options (existing doc is woefully incomplete and outdated and the associated automation is long-broken)
- Update language tour for Scala 3 (code samples were updated but new sections are needed)
- Update The Scala 3 Book (donated to the Scala web site by Alvin Alexander) for new Scala versions and features
- Write a new guide on Scala/Java interoperability
7 Likes
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.
6 Likes
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
1 Like
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.
3 Likes