> The documentation seems to require a phd, which I have, just not in esoteric type system kungfoo.
Completely agreed. Though the funny thing is, Scala has/had a Documentation Tzar and she is trying to get things to a better place. To supposedly take care of this. I'm very much a learn by example type, so I'd appreciate a lot more examples (e.g. for methods: https://www.scala-lang.org/api/2.12.6/scala/collection/$colo... ). On the other hand, the documentation is open source in the best way: https://github.com/scala/docs.scala-lang/commits/master anyone can shoot a PR if they feel they can/want-to contribute. And there's plenty of overview articles ( https://github.com/scala/docs.scala-lang/tree/master/_overvi... ) covering a wide range of topics.
Sometimes the fault is with the libraries and their documentation. Especially anything that's HC FP (scalaz : Let the types speak for themselves via the Scalaz Scaladocs! and then you're completely at the deep end - for example: https://static.javadoc.io/org.scalaz/scalaz_2.12/7.2.24/scal...):F[(A,B)] ).
What makes Scala code unreadable is - IMHO - that people rely too much on the IDE to help them understand and navigate code, or their own familiarity with that code (or in some cases the code is simply write only, making it more like obfuscated Perl and KDB+/Q than a modern object-functional hybrid language).
And since Scala has so many faculties, features, facilities to mange code, to abstract problems and their solutions, and people write almost none of their design choices down into READMEs or comments, we're left with the code. For some people it speaks for itself. (For some people types like a -> a tell everything, for me that's just a function with unknown "functionality", because it depends on what the fuck the function actually does. Sure, the type signature constrains the expected return value, and it's useful, but that's not the architecture, not the rationale of/for design choices, it's just the safety striping around the sharp edges.)
Somehow Scala is "the PHP" at the other end of the spectrum. Instead of being too little it usually ends up being too much (insert the relevant Paul Philips rants here), while both are perfectly capable of expressing nicely designed programs/systems.
Furthermore, Scala is actually a bit weak when it comes to expressing really high level concepts. So yes, you can do a lot of magic in it, but most of it ends up being of the Black variety, because "for performance" (minimize GC pressure) or because that part is still "experimental" (macros/reflection) or because that part is just ugly and badly designed (collections).