20 ms·

The state of the Scala website and documentation

133 points by 0xmohit 10y ago

alyandon 10y ago
I think the author hit upon some pretty good points. Several years ago when I started poking around Scala I really had to push myself to work with it and especially with respect to simple thigns like do I download SBT or Scala. One of the more personally frustrating things I found as a newbie is that the bulk of the documentation seemed to be written as a reference. Compounding that was the un-googlable nature of some of the operators like ":<" which really made things more difficult than I felt that they needed to be. Regardless, although it was not what I would describe as a pleasant experience, after working with Scala for a few months I definitely found languages like Haskell a lot easier to comprehend. So, I obviously managed to internalize something. :-D
- Fiahil 10y ago
  > Compounding that was the un-googlable nature of some of the operators like ":<" Ah! souvenirs "- [..] Oh, but you have to use the epaulette function! - The what? - The epaulette! (>>>) it's like the zigouigoui, but you don't have to lift anything. Just flatMap that shit and you're good."
  - saosebastiao 10y ago
    My biggest technical complaint about Scalaz. You can't effectively communicate concepts that involve nameless symbolic constructs, and slang as a replacement is inherently exclusionary.
    - adriaanm 10y ago
      I see how people might look at how close java & javax are, and think scala & scalaz are equally close. They are not. Scalaz is a completely separate project from the core Scala project.
    - runT1ME 10y ago
      Scalaz has (or should have) ascii names for every method I believe. If you can find examples otherwise we can fix it.
    - znpy 10y ago
      This reminds me of that short time I've been working with scala... I honestly think Scala is Perl on the JVM. I mean, the write-only unreadable-code part of Perl, but on the JVM.
      - the_af 10y ago
        Can you provide examples? There's a lot to criticize in Scala, but I can't find many examples of symbol soup, especially in user-written code. There is some, sure (most languages suffer from this to a degree), but so many you consider the language write-only? I just don't see it. Keep in mind Scalaz is not Scala.
1_800_UNICORN 10y ago
Interesting discussion. Thanks for posting. As I've gotten to learn many different languages (PHP, Ruby, Go, Java, Python, etc) over the last 10 years, it has been really interesting to see how different languages and communities can vary so wildly in their quality of documentation. As it relates to programming languages, Go's "Tour of Go" (https://tour.golang.org/welcome/1 https://tour.golang.org/welcome/1) is an excellent introduction to the language. I wish every language had an intro guide as good. In terms of frameworks, I absolutely love the Ruby on Rails guides. They strike the right balance between staying high level enough for me to build a mental model of how the framework is working under the hood, while getting deep enough to be useful to solve individual problems I have. Overall, I think the Ruby community has done a great job of documenting their libraries and frameworks. Whether it's Rails or Sinatra, or it's a library like Devise, Ruby OSS projects seem to tend towards thorough documentation. On the flip side, Spring's documentation (and most Java library documentation) is absolutely atrocious. Spring in particular only seems to give you 2 flavors of documentation: a 10-minute tutorial, or a 1000-page deep dive in all of the corners of the framework. And Java libraries in general seem to have miserable, out-of-date, incomplete documentation.
- agentgt 10y ago
  > On the flip side, Spring's documentation (and most Java library documentation) is absolutely atrocious. Spring in particular only seems to give you 2 flavors of documentation: a 10-minute tutorial, or a 1000-page deep dive in all of the corners of the framework. And Java libraries in general seem to have miserable, out-of-date, incomplete documentation. I actually find the opposite with Java libraries. They are generally over documented but are complete. The issue is that many have issues with publishing doc/Javadoc (with github it is slightly non trivial) and thus are outdated. Java projects have also been around a lot longer so some of them use archaic doc formats like docbook (spring). However the biggest problem with Java documentation is the accessibility of the standard language + javax stuff (ie jdk + jee). IMO Oracle does a piss poor job of this. You have to register and it is either in some messed up help tree format or some PDF that is impossible to download. On the other hand Apache and Spring I think are far far far more detailed in documentation than your standard PHP, Ruby, Python projects. The documentation may not be as pretty but it is there. I stress that because many languages and libraries lack specifications or review processes (even still) and Java was doing it fairly early (albeit with various corporate agendas).
0xmohit 10y ago
We are basically filtering our audience down to people who can either invest plenty of time (to wade through the documentation/ask for help on the mailing lists and gitter), money (to pay for training or attend conferences) or both. .. I think it wouldn't be charitable to think that the state of documentation is a result of the involved parties' massive conflict of interest, as Lightbend (has partners that sell training), EPFL and ScalaCenter (receive money from commercial Coursera courses) all profit from the current situation financially. This hits the nail on the head.
- partycoder 10y ago
  Linus said once that if the only benefit of using C for Linux was excluding C++ programmers, that was enough of a benefit. Sounds really negative, but to be honest, sometimes if the only benefit of Scala is excluding people that are not comfortable with advanced programming, for a project that requires it, then great. You saved your recruiters the job of looking over a lot of resumes that you didn't want anyways. Scala is not incredibly hard. I am not gifted and I managed to learn it to an extent in which I could solve practical problems. That being said, I think learning Scala comes out more naturally when you have some exposure to Java. Since many Scala constructs are really shorthands for longer Java code. I have to accept though that some people go really hardcore on the functional side (like the typelevel/scalaz folks) and that can be really intimidating.
  - geofft 10y ago
    You're also saving your recruiters the job of looking over a lot of resumes from people who have productive full-time jobs in another language and have limited time to pick up a new language because they're busy delivering business value in their existing language. It's a very high-false-positive strategy.
    - partycoder 10y ago
      Very true, geofft. Sometimes you can formulate your job posting like: Scala or Java, with preferred Scala experience. I had issues when trying to recruit for a Scala position, and we expanded the search a little bit to include senior Java programmers too.
geodel 10y ago
It could be the case that Scala language and docs are really done from perspective of maintainers. When I look at commits this year on github [1], there are about half dozen people making significant contribution and most of them seems to be associated with Lightbend. Other popular languages e.g Java/Rust/Swift/Go have very vibrant commit activity from lots of contributors https://github.com/scala/scala/graphs/contributors?from=2016-01-03&to=2016-10-15&type=c https://github.com/scala/scala/graphs/contributors?from=2016...
- deleted 10y ago
  [deleted]
runeblaze 10y ago
The website of Scala.js is devoid of some of the problems mentioned. It has an in-browser playground, a getting started guide that uses sbt and follows development conventions, and a useful list of libraries. Maybe Scala can learn a bit from Scala.js? EDIT: small grammar error
pm24601 10y ago
I find this incredibly sad. Plenty great products/languages have died because of poor documentation, poor respect for beginners. Yet... here the Scala community is... repeating the past and justifying with the same reasons. I personally only spend time learning a new language when: 1. I can get employed because I know it. (example: python) 2. It is easy to pick up and learn. (example: arduino ) 3. It solves a problem I must solve ( perl/bash scripting ) Scala doesn't meet any of the above criteria.
- dudul 10y ago
  There are a lot of Scala jobs. And they usually pay much better than Python jobs. Not discussing your 2 other points since they are pretty subjective.
- tormeh 10y ago
  If you can program Java you can program Scala. You can't write good Scala code, but that (hopefully) comes with time. Scala solves the same problems Java does, just better. And there are lots of jobs for Scala. Not as many as there are for Java or Python, but maybe as many as for Ruby? I'm not sure exactly.
  - bsder 10y ago
    > If you can program Java you can program Scala. Clojure would probably be my choice nowadays rather than Scala. Clojure has a great community and is a good counter example to the Lisper's whining that the syntax is what keeps people away. If I truly needed Actor stuff for performance, I'm probably going leave the JVM and reach for Erlang anyway.
    - the_af 10y ago
      Clojure is great, but the more natural progression is from Java to Scala, not to Clojure, if only because you can program in Scala as if it were Java++. You won't write the best Scala, but it will work and you can look at it as "Java with weird syntax". Going from Java to Clojure requires a major mental shift :)
Noseshine 10y ago
That's interesting. Just a few days ago with great regret I decided to drop the (free) Scala course on Coursera after almost finishing week #3 (of 5 I think). I'm actually already pretty familiar at least with the essentials of functional programming but would like to go even deeper. However, I found the step too steep between the easy to understand lectures and the exercises, and the latter not as useful as they could be. It felt like I was suddenly dropped off and left to my own devices with no guidance. "Now implement this!" Uhm... what? Sure, that's easy, I've been implementing much more complicated things for decades. The problem is I have no idea how to approach it "the right way" as far as Scala is concerned, that's why I'm taking the course! Looking at the forum - extremely sparsely populated even after over 4 months - showed that I could also expect no guidance from there. That meant that even when I finished a task I was unable to find out if what I had done was the right (functional) way. For one and most importantly, there is hardly anyone to respond, but also since the only exercises are the homework assignments you can't just post your code, that's an "honor code violation". There also is no "solution", i.e. you can't see how the course author(s) would have implemented it. Another example, people in the forum complained about extreme differences in performance for very minor differences in the way you wrote something, and you had to find all of this out completely for yourself, again no guidance at all. Another point is that I found the problems too academic. Sure, I can walk a list of head.tail or a tree of left.element.right tuples. But overall the problems were all from what I did a long time ago at university and it felt very, very far from what I deal with now - and I don't just do CRUD or other boring stuff and actually do have interesting algorithms to implement. The course feels like being made for university students - in a negative way. Overall I found the course more frustration than it was worth. I could have solved the programming challenges easily enough in a way I already knew, but what's the point? I wanted to learn the new (Scala) way, but felt all alone in trying to do that. The course was like a good violin player demonstrating a piece and then giving me some sheet music and shoving me out the door "come back when you can play that". It's hard to complain about "free", but if course forum participation is a guide, both total numbers as well as the steep drop-off after week 1 and 2, it isn't very successful. The course: https://www.coursera.org/learn/progfun1 https://www.coursera.org/learn/progfun1 Note: Enrolling in the courses individually is possible for free, going through the "specialization" page at https://www.coursera.org/specializations/scala https://www.coursera.org/specializations/scala only shows the for-pay option.
bigredhdl 10y ago
Personally this is interesting to see after I just recently tried to learn a little Scala to see if I could realize the promise of a fluid front-end to to back-end experience between Scala and Scala.js. I eventually gave up in defeat because the documentation and tools just didn't make for a smooth enough jumpstart for me. Maybe people coming from Java just already have enough prerequisite knowledge to get past that but for me I just wasn't progressing very fast. I had a much easier time progressing in Elixir/Phoenix and Elm recently and to a lesser extent F#. Just my two cents...
- sotojuan 10y ago
  Elixir shines by how easy it makes it to write good documentation. The Markdown-renderd docstrings for modules and functions can be converted into nice websites[1] or are available in the command line[2]. [1] http://elixir-lang.org/docs/stable/elixir/Enum.html#map/2 http://elixir-lang.org/docs/stable/elixir/Enum.html#map/2 [2] https://i.imgur.com/RhS283f.png https://i.imgur.com/RhS283f.png
- yawaramin 10y ago
  Yeah, there is quite a bit of project management and juggling needed to set up a ScalaJVM/Scala.js shared project. Maybe this would help you? https://www.scala-js.org/libraries/skeletons.html https://www.scala-js.org/libraries/skeletons.html
danpalmer 10y ago
This pull request showed me just how much the Scala community values good documentation: https://github.com/playframework/playframework/pull/6545 https://github.com/playframework/playframework/pull/6545 – tldr: not much. I work a lot with Django, and the documentation is amazing. It's up to date, cross-referenced, everything is linked to everything else, code is executable, etc. Here, rather than a 2 line fix to make the code in the examples executable and explain how some data is being used, the maintainers opt to keep the code examples non-executable, and obfuscate the code, expanding explanations in text to make up for it. Documentation is important. If someone doesn't understand it, the project should make a sincere attempt to understand why, take on feedback, instead of shutting down discussion and dismissing someones lack of understanding.
- dozzie 10y ago
  > This pull request showed me just how much the Scala community values good documentation: https://github.com/playframework/playframework/pull/6545 https://github.com/playframework/playframework/pull/6545 – tldr: not much. Erm... But the change was shitty. How would that make good documentation? The phrase just before said "Here's example JSON", and the JSON got changed to Scala code. How is that indication of appreciation or not of good documentation?
  - smallnamespace 10y ago
    Not to mention the same doc page already showed how to convert JSON into a Scala value earlier.
- merb 10y ago
  well if you work a lot with Django than you have the same stuff like that aswell: > https://docs.djangoproject.com/en/1.10/howto/initial-data/ https://docs.djangoproject.com/en/1.10/howto/initial-data/ > https://docs.djangoproject.com/en/1.10/topics/serialization/#xml https://docs.djangoproject.com/en/1.10/topics/serialization/... of course you can't just use it directly in Python. Documentation is about reading, 90% of the stuff is just reading. And there is clearly everything said about the snippet above the snippet: "In the code samples below, we’ll use the following JSON:". Since you already visited the last page, you should've probably already understood how to parse the Json. I see a lot of issue's on a daily basis and I even give some examples if needed, even if a discussion should take place on a mailing list, however I think before ANY issue should be made, people should carefully read and check if there is even an issue. But Playframework's documentation is already really good. There are some cases which aren't described so good, but they aren't even well described in Django I guess, what I mean is testing, a lot of this topic is not easy and you probably learn on your way of getting a better developer to get better in it. I started to contribute to Play! In the middle/start of the year and a lot of people are just helpful (and busy). And I've seen plenty of one character spelling mistakes merged. If something is not strictly understandable we even give a advice to discuss it on the mailing list.
partycoder 10y ago
Scala documentation is a bit hard to understand, some articles do not have a good balance in their level of detail... e.g: documentation for Futures and Promises. I use text-to-speech to read it since it can be a bit dense. Scala.js is great, but it is different (numeric primitives, threads, to start with).
philipkglass 10y ago
Scala was my first serious use of a JVM language and I kept hitting little rough patches that people were assumed to understand from a prior Java background. One example: a month or so into my use I started getting a puzzling failure when sbt was trying to download a dependency. Everybody already knows about Java's security certificate handling, Ivy, and Maven, right? I didn't. I kept on Googling the wrong terms because I was searching for Scala and sbt. The problem turned out (IIRC) to be a dependency download attempt that started from a URL whose certificate was trusted and then got 302 redirected to a mirror whose certificate was not yet trusted by Java. The error messages that actually showed up in my console were not at all helpful and I ended up using tcpflow and a Java-savvy colleague to figure out what was actually happening. Would it be so hard for (e.g.) sbt to provide an interactive security prompt for if you want to trust a remote source's security cert, rather than expecting you to figure out the error message and solve it the Java way with plain Java tools? (Maybe it would be hard. Maybe that's why it doesn't do that. I don't know because I didn't use Java before Scala.) I don't have concrete examples to hand for the other rough spots but I recall hitting other areas of knowledge that are explained via Java instead of standing on their own. "The Scala Bar is like Java's Foo, but with these improvements..." I never learned the Java Foo and I don't really want to have to acquire a working Java developer's knowledge to use Scala. I'm using Scala and not Java. If you're writing docs for Scala and the reader needs to know something important about either Java-the-ecosystem or Java-the-language, please inline that knowledge.
- lmm 10y ago
  I wouldn't recommend SBT, especially for beginners (Maven is much better documented), but no, it can't give you a prompt because programs don't have access to modify the keystore by design. The JVM is one of the few platforms that actually has a decent go at security, which sometimes means usability suffers.
  - jackcviers3 10y ago
    To use scala effectively, you must use SBT. Almost every scala library and framework is built using it. There are tons of productivity enhancing tools wrapped in plug-ins for it. It is java, scala and scalajs aware, and incrementally compiles large projects if you use it. The documentation for it is good from version 0.12 on. You can learn 90% of what you need to do scala builds in SBT in 4 hours by reading the documentation and the walk-through tutorial. Eventually you may need to write your own tasks, but 90% of those tasks are covered by the existing plug-ins available, and you can easily modify or create a new task by writing some simple scala function on your first day using the tool without having to publish a plug-in to some repo for it to work. I absolutely would reccommend SBT for beginner scala users. It's a must to use and understand it, as much a part of understanding scala as understanding for comprehensions, case classes, and if/else expressions.
bsder 10y ago
Excellent. I can now point to this for a good objective reason to not use Scala. Actually, I'm really sad. I used Scala back in 2005 (Edit: Corrected from 2001?) (God, I'm old) for it's Actors model to do peer-to-peer networking protocols. It was SOOOOOO much better than C/C++ and I could deploy stuff without installation across multiple architectures. I'm especially sad because it seems like Scala always needed just a little more sustained effort on the community front to move into the big time and it never really got it.
- hocuspocus 10y ago
  Scala came out in early 2004, Scala 2.0 in 2006 and I'm not sure about actors but probably not before 2007. In 2001 Martin's lab was probably working on Pizza / Java generics :)
  - bsder 10y ago
    You are quite correct, I just looked at one of the domains I registered for that and the date was 2005. As for actors, I was definitely using alpha level stuff. So, your dates jibe with that. Apparently I'm getting old enough that my memory is getting faulty. :) Now, if I could only figure out how to do strikethrough for edits...
- yawaramin 10y ago
  I wouldn't be that sad. Bad docs may be a good objective reason not to use Scala, but there may well be even better objective reasons to use it, like doing data science with Spark, or even building resilient fault-tolerant systems with Akka. The final calculation will, as always, rest with each potential user.
Fiahil 10y ago
I write Scala code professionally, and the language documentation is the worst I've encountered. Luckily, I've leveled-up to the point where I don't need it anymore and can just lookup prototypes and comments directly in the source code when I need it (thing almost everyone is doing after a certain time, btw). I understand the frustration of beginners, and I've even began to host talks/presentations, inside my company, for a few coworkers. I hope to get them past, at least, past the few interesting concepts and the shitload of symbols/operators/random-combinations-of-chars-on-my-keyboard that you encounter on a day-to-day basis.
- cle 10y ago
  This is not an excuse for poor documentation, but I've found that not relying on documentation in general vastly improves my productivity. It requires being comfortable digging into the innards of the libraries and frameworks I use, which helps me understand performance characteristics, extension points, understand stack traces, understand failures when they happen, find bugs, learn language idioms, etc.
allengeorge 10y ago
I am completely unsurprised. I've been pretty negative on Scala in the past, and this is one of those reasons. The community does not feel inclusive and, my perception is that as a beginner you're simply expected to deal with the lack of documentation, the odd behavior of the tools, etc. And that (frankly) makes me fairly uninterested in contributing back to it. I wonder if it's because many people who stay with Scala are more interested in the many advanced language features it offers, as opposed to building libraries to be used by day-to-day practitioners (who have very different metrics for deciding if a library is worthwhile or not).
- runT1ME 10y ago
  I'm not sure what you mean by building libraries to be used 'day-to-day'. If you mean that the Scala community is in general more interested in building libraries/tools used by professionals than hobbyists I'd agree, but I can't think of any popular libraries that aren't used day to day by all of the developers on our very very large scala team.
  - allengeorge 10y ago
    Out of curiosity, which libraries does your team use?
    - runT1ME 10y ago
      Scalaz, Scalaz-Stream and http4s constantly. Doobie, Spray, Shapeless, Monocle, and others less often but still definitely more than rarely.
ape4 10y ago
How about the speed of the compiler? Last I used Scala, that was the deal breaker for me.
petetnt 10y ago
I dove deep into Scala a short while back and I can concur with those that thought the documentation was sub-par almost all around, from Scala-Lang site itself, to big things like Play Framework to across small userland libraries. The saddest thing was that I wanted to improve those docs, but I didn't know how. When I finally got to the point through tedious trial and error, I couldn't even remember where to start. It doesn't help that there's 10 ways in Scala to do everything, but no way to find out which is the best one, or the worst, or one that even just works with your current version. Surely this the tone of this post is quite whiny, but it really did make Scala hard as hell to approach.
cutler 10y ago
Scala's poor documentation stems from a much more fundamental problem - the absence of a Clojars/Rubygems/PyPI for Scala libraries. It's in the process of being fixed now, I believe, but why did it take so long? The Clojure community has a much lower profile in industry than Scala yet right from the beginning they really valued their community and produced an excellent repository for Clojure libraries and an easy-to-use build tool - Leiningen. The Scala community, by contrast, comes across to outsiders as just not that interested in community. Maybe it's the Java legacy.
philipkglass 10y ago
I remembered another thing that Java users already know but surprised me in Scala in a bad way: null. I read a lot about Scala's type system in the week between I was hired to write Scala and when I actually started writing code. Most of it was about how great Scala's type system was and how much safety it provided; the company even called itself Typesafe then. I read many paeans to the virtues of Scala's type system that would turn runtime errors into compile time errors, but they didn't highlight that it can't prevent that most common and annoying of Java runtime errors, the NullPointerException. Due to a lack of prominent mentions in the Scala docs and tutorials I read, I thought that Scala authors either didn't have to think about Java's Billion Dollar Mistake or that the compiler would guide them to safety before the code could blow up at runtime. Maybe manually dealing with nulls is supposed to just be assumed by anyone using the JVM... But I'd used Jython a little in the past and I didn't have to explicitly deal with null-checking then. Jython converts null to None. In the absence of prominent warnings to the contrary I had thought that Scala would provide at least as much automatic safety as Python-on-JVM does.
- aianus 10y ago
  The correct way to handle this in Scala is to wrap the possibly-null reference (which I assume you're getting as a return value from some Java library) in Option(), not manually checking for null.
  - philipkglass 10y ago
    By "manually checking" I mean that I have to use my own brainpower to notice places where null can leak in to code I'm writing; the compiler doesn't actually enforce the type safety I thought I had. I do use Option to handle sometimes-nulls after I notice them. EDIT: since Jython doesn't allow raw nulls to leak in from Java libraries, and Kotlin prevents accidental use of nullable values at compile time, it naively seems like Scala could prevent accidental null introduction despite living on the JVM. Or as a distant second-best, prominently warn about the perils of null whenever introducing its type system to beginners.
    - 10y ago
jomamaxx 10y ago
A production is only as good as it's training and docs. I would go a step further: 'Training and Docs ARE the Product'. Having bad docs is like selling a car without wheels -> It's not a car :), rather, not a thing that 'solves the problem of getting people from point A to point B'. My experience with Scala has generally led me to concur with the overall assessment that Scala information and communication is pretty weak. Hope they can improve it, it's a pretty cool language.
horusthecat 10y ago
I really wanted to pursue Scala. It looked promising: runs on the JVM, is far saner than Java, has features that keep the "Java 1.4 was the last real Java" crowd away, has a mixed-paradigm OO/FP approach, lots of features... things like all the FUD over compile times and performance didn't really bother me (if I cared about resource usage/performance, I wouldn't use the JVM, duh). I found two classes of problems. The first was the lack of practical guides. How do I access a database? Should I use a Java lib for that? What about a rudimentary CRUD app? What if i need something Java-EE-ish, like a message queue/IPC? I kept finding myself in scenarios where I had to reach out to Java, which I was deliberately trying to migrate away from. Second, there's the fact that Scala has full OO along with the ML-style FP, which makes it hard to figure out if I was doing things the "right" way. Do i use traits and composition and case classes? Should methods go on classes? What's up with the Object pattern? Do I store state on classes or should I prefer case class/record types? When is it a judgment call... and if it is a judgment call... how do I make it without much experience in the language or having any experienced Scala users to guide me? I'm not averse to spending $100 on books and working through them. I tried that with Scala, but somewhere around page 200 of Programming Scala, gave up. Then there's the scare factor, there are so many "we're switching from Scala to Java 8" or "we already use Grails" that it was looking like it was turning into a dead end professionally very quickly, especially outside of DC/NY/SF/Chicago. One job I was looking at told me they were moving all their Scala work into Java because of client pressure. The bigger irony being that I started using OCaml instead, a language where the documentation is usually just an interface file and type signatures.

133 points by 0xmohit 10y ago

I think the author hit upon some pretty good points. Several years ago when I started poking around Scala I really had to push myself to work with it and especially with respect to simple thigns like do I download SBT or Scala. One of the more personally frustrating things I found as a newbie is that the bulk of the documentation seemed to be written as a reference. Compounding that was the un-googlable nature of some of the operators like ":<" which really made things more difficult than I felt that they needed to be. Regardless, although it was not what I would describe as a pleasant experience, after working with Scala for a few months I definitely found languages like Haskell a lot easier to comprehend. So, I obviously managed to internalize something. :-D

Fiahil 10y ago
> Compounding that was the un-googlable nature of some of the operators like ":<" Ah! souvenirs "- [..] Oh, but you have to use the epaulette function! - The what? - The epaulette! (>>>) it's like the zigouigoui, but you don't have to lift anything. Just flatMap that shit and you're good."
- saosebastiao 10y ago
  My biggest technical complaint about Scalaz. You can't effectively communicate concepts that involve nameless symbolic constructs, and slang as a replacement is inherently exclusionary.
  - adriaanm 10y ago
    I see how people might look at how close java & javax are, and think scala & scalaz are equally close. They are not. Scalaz is a completely separate project from the core Scala project.
  - runT1ME 10y ago
    Scalaz has (or should have) ascii names for every method I believe. If you can find examples otherwise we can fix it.
  - znpy 10y ago
    This reminds me of that short time I've been working with scala... I honestly think Scala is Perl on the JVM. I mean, the write-only unreadable-code part of Perl, but on the JVM.
    - the_af 10y ago
      Can you provide examples? There's a lot to criticize in Scala, but I can't find many examples of symbol soup, especially in user-written code. There is some, sure (most languages suffer from this to a degree), but so many you consider the language write-only? I just don't see it. Keep in mind Scalaz is not Scala.

1_800_UNICORN 10y ago

Interesting discussion. Thanks for posting. As I've gotten to learn many different languages (PHP, Ruby, Go, Java, Python, etc) over the last 10 years, it has been really interesting to see how different languages and communities can vary so wildly in their quality of documentation. As it relates to programming languages, Go's "Tour of Go" (https://tour.golang.org/welcome/1 https://tour.golang.org/welcome/1) is an excellent introduction to the language. I wish every language had an intro guide as good. In terms of frameworks, I absolutely love the Ruby on Rails guides. They strike the right balance between staying high level enough for me to build a mental model of how the framework is working under the hood, while getting deep enough to be useful to solve individual problems I have. Overall, I think the Ruby community has done a great job of documenting their libraries and frameworks. Whether it's Rails or Sinatra, or it's a library like Devise, Ruby OSS projects seem to tend towards thorough documentation. On the flip side, Spring's documentation (and most Java library documentation) is absolutely atrocious. Spring in particular only seems to give you 2 flavors of documentation: a 10-minute tutorial, or a 1000-page deep dive in all of the corners of the framework. And Java libraries in general seem to have miserable, out-of-date, incomplete documentation.

agentgt 10y ago
> On the flip side, Spring's documentation (and most Java library documentation) is absolutely atrocious. Spring in particular only seems to give you 2 flavors of documentation: a 10-minute tutorial, or a 1000-page deep dive in all of the corners of the framework. And Java libraries in general seem to have miserable, out-of-date, incomplete documentation. I actually find the opposite with Java libraries. They are generally over documented but are complete. The issue is that many have issues with publishing doc/Javadoc (with github it is slightly non trivial) and thus are outdated. Java projects have also been around a lot longer so some of them use archaic doc formats like docbook (spring). However the biggest problem with Java documentation is the accessibility of the standard language + javax stuff (ie jdk + jee). IMO Oracle does a piss poor job of this. You have to register and it is either in some messed up help tree format or some PDF that is impossible to download. On the other hand Apache and Spring I think are far far far more detailed in documentation than your standard PHP, Ruby, Python projects. The documentation may not be as pretty but it is there. I stress that because many languages and libraries lack specifications or review processes (even still) and Java was doing it fairly early (albeit with various corporate agendas).

0xmohit 10y ago

We are basically filtering our audience down to people who can either invest plenty of time (to wade through the documentation/ask for help on the mailing lists and gitter), money (to pay for training or attend conferences) or both. .. I think it wouldn't be charitable to think that the state of documentation is a result of the involved parties' massive conflict of interest, as Lightbend (has partners that sell training), EPFL and ScalaCenter (receive money from commercial Coursera courses) all profit from the current situation financially. This hits the nail on the head.

partycoder 10y ago
Linus said once that if the only benefit of using C for Linux was excluding C++ programmers, that was enough of a benefit. Sounds really negative, but to be honest, sometimes if the only benefit of Scala is excluding people that are not comfortable with advanced programming, for a project that requires it, then great. You saved your recruiters the job of looking over a lot of resumes that you didn't want anyways. Scala is not incredibly hard. I am not gifted and I managed to learn it to an extent in which I could solve practical problems. That being said, I think learning Scala comes out more naturally when you have some exposure to Java. Since many Scala constructs are really shorthands for longer Java code. I have to accept though that some people go really hardcore on the functional side (like the typelevel/scalaz folks) and that can be really intimidating.
- geofft 10y ago
  You're also saving your recruiters the job of looking over a lot of resumes from people who have productive full-time jobs in another language and have limited time to pick up a new language because they're busy delivering business value in their existing language. It's a very high-false-positive strategy.
  - partycoder 10y ago
    Very true, geofft. Sometimes you can formulate your job posting like: Scala or Java, with preferred Scala experience. I had issues when trying to recruit for a Scala position, and we expanded the search a little bit to include senior Java programmers too.

geodel 10y ago

It could be the case that Scala language and docs are really done from perspective of maintainers. When I look at commits this year on github [1], there are about half dozen people making significant contribution and most of them seems to be associated with Lightbend. Other popular languages e.g Java/Rust/Swift/Go have very vibrant commit activity from lots of contributors https://github.com/scala/scala/graphs/contributors?from=2016-01-03&to=2016-10-15&type=c https://github.com/scala/scala/graphs/contributors?from=2016...

deleted 10y ago
[deleted]

runeblaze 10y ago

The website of Scala.js is devoid of some of the problems mentioned. It has an in-browser playground, a getting started guide that uses sbt and follows development conventions, and a useful list of libraries. Maybe Scala can learn a bit from Scala.js? EDIT: small grammar error

pm24601 10y ago

I find this incredibly sad. Plenty great products/languages have died because of poor documentation, poor respect for beginners. Yet... here the Scala community is... repeating the past and justifying with the same reasons. I personally only spend time learning a new language when: 1. I can get employed because I know it. (example: python) 2. It is easy to pick up and learn. (example: arduino ) 3. It solves a problem I must solve ( perl/bash scripting ) Scala doesn't meet any of the above criteria.

dudul 10y ago
There are a lot of Scala jobs. And they usually pay much better than Python jobs. Not discussing your 2 other points since they are pretty subjective.
tormeh 10y ago
If you can program Java you can program Scala. You can't write good Scala code, but that (hopefully) comes with time. Scala solves the same problems Java does, just better. And there are lots of jobs for Scala. Not as many as there are for Java or Python, but maybe as many as for Ruby? I'm not sure exactly.
- bsder 10y ago
  > If you can program Java you can program Scala. Clojure would probably be my choice nowadays rather than Scala. Clojure has a great community and is a good counter example to the Lisper's whining that the syntax is what keeps people away. If I truly needed Actor stuff for performance, I'm probably going leave the JVM and reach for Erlang anyway.
  - the_af 10y ago
    Clojure is great, but the more natural progression is from Java to Scala, not to Clojure, if only because you can program in Scala as if it were Java++. You won't write the best Scala, but it will work and you can look at it as "Java with weird syntax". Going from Java to Clojure requires a major mental shift :)

Noseshine 10y ago

That's interesting. Just a few days ago with great regret I decided to drop the (free) Scala course on Coursera after almost finishing week #3 (of 5 I think). I'm actually already pretty familiar at least with the essentials of functional programming but would like to go even deeper. However, I found the step too steep between the easy to understand lectures and the exercises, and the latter not as useful as they could be. It felt like I was suddenly dropped off and left to my own devices with no guidance. "Now implement this!" Uhm... what? Sure, that's easy, I've been implementing much more complicated things for decades. The problem is I have no idea how to approach it "the right way" as far as Scala is concerned, that's why I'm taking the course! Looking at the forum - extremely sparsely populated even after over 4 months - showed that I could also expect no guidance from there. That meant that even when I finished a task I was unable to find out if what I had done was the right (functional) way. For one and most importantly, there is hardly anyone to respond, but also since the only exercises are the homework assignments you can't just post your code, that's an "honor code violation". There also is no "solution", i.e. you can't see how the course author(s) would have implemented it. Another example, people in the forum complained about extreme differences in performance for very minor differences in the way you wrote something, and you had to find all of this out completely for yourself, again no guidance at all. Another point is that I found the problems too academic. Sure, I can walk a list of head.tail or a tree of left.element.right tuples. But overall the problems were all from what I did a long time ago at university and it felt very, very far from what I deal with now - and I don't just do CRUD or other boring stuff and actually do have interesting algorithms to implement. The course feels like being made for university students - in a negative way. Overall I found the course more frustration than it was worth. I could have solved the programming challenges easily enough in a way I already knew, but what's the point? I wanted to learn the new (Scala) way, but felt all alone in trying to do that. The course was like a good violin player demonstrating a piece and then giving me some sheet music and shoving me out the door "come back when you can play that". It's hard to complain about "free", but if course forum participation is a guide, both total numbers as well as the steep drop-off after week 1 and 2, it isn't very successful. The course: https://www.coursera.org/learn/progfun1 https://www.coursera.org/learn/progfun1 Note: Enrolling in the courses individually is possible for free, going through the "specialization" page at https://www.coursera.org/specializations/scala https://www.coursera.org/specializations/scala only shows the for-pay option.

bigredhdl 10y ago

Personally this is interesting to see after I just recently tried to learn a little Scala to see if I could realize the promise of a fluid front-end to to back-end experience between Scala and Scala.js. I eventually gave up in defeat because the documentation and tools just didn't make for a smooth enough jumpstart for me. Maybe people coming from Java just already have enough prerequisite knowledge to get past that but for me I just wasn't progressing very fast. I had a much easier time progressing in Elixir/Phoenix and Elm recently and to a lesser extent F#. Just my two cents...

sotojuan 10y ago
Elixir shines by how easy it makes it to write good documentation. The Markdown-renderd docstrings for modules and functions can be converted into nice websites[1] or are available in the command line[2]. [1] http://elixir-lang.org/docs/stable/elixir/Enum.html#map/2 http://elixir-lang.org/docs/stable/elixir/Enum.html#map/2 [2] https://i.imgur.com/RhS283f.png https://i.imgur.com/RhS283f.png
yawaramin 10y ago
Yeah, there is quite a bit of project management and juggling needed to set up a ScalaJVM/Scala.js shared project. Maybe this would help you? https://www.scala-js.org/libraries/skeletons.html https://www.scala-js.org/libraries/skeletons.html

danpalmer 10y ago

This pull request showed me just how much the Scala community values good documentation: https://github.com/playframework/playframework/pull/6545 https://github.com/playframework/playframework/pull/6545 – tldr: not much. I work a lot with Django, and the documentation is amazing. It's up to date, cross-referenced, everything is linked to everything else, code is executable, etc. Here, rather than a 2 line fix to make the code in the examples executable and explain how some data is being used, the maintainers opt to keep the code examples non-executable, and obfuscate the code, expanding explanations in text to make up for it. Documentation is important. If someone doesn't understand it, the project should make a sincere attempt to understand why, take on feedback, instead of shutting down discussion and dismissing someones lack of understanding.

dozzie 10y ago
> This pull request showed me just how much the Scala community values good documentation: https://github.com/playframework/playframework/pull/6545 https://github.com/playframework/playframework/pull/6545 – tldr: not much. Erm... But the change was shitty. How would that make good documentation? The phrase just before said "Here's example JSON", and the JSON got changed to Scala code. How is that indication of appreciation or not of good documentation?
- smallnamespace 10y ago
  Not to mention the same doc page already showed how to convert JSON into a Scala value earlier.
merb 10y ago
well if you work a lot with Django than you have the same stuff like that aswell: > https://docs.djangoproject.com/en/1.10/howto/initial-data/ https://docs.djangoproject.com/en/1.10/howto/initial-data/ > https://docs.djangoproject.com/en/1.10/topics/serialization/#xml https://docs.djangoproject.com/en/1.10/topics/serialization/... of course you can't just use it directly in Python. Documentation is about reading, 90% of the stuff is just reading. And there is clearly everything said about the snippet above the snippet: "In the code samples below, we’ll use the following JSON:". Since you already visited the last page, you should've probably already understood how to parse the Json. I see a lot of issue's on a daily basis and I even give some examples if needed, even if a discussion should take place on a mailing list, however I think before ANY issue should be made, people should carefully read and check if there is even an issue. But Playframework's documentation is already really good. There are some cases which aren't described so good, but they aren't even well described in Django I guess, what I mean is testing, a lot of this topic is not easy and you probably learn on your way of getting a better developer to get better in it. I started to contribute to Play! In the middle/start of the year and a lot of people are just helpful (and busy). And I've seen plenty of one character spelling mistakes merged. If something is not strictly understandable we even give a advice to discuss it on the mailing list.

partycoder 10y ago

Scala documentation is a bit hard to understand, some articles do not have a good balance in their level of detail... e.g: documentation for Futures and Promises. I use text-to-speech to read it since it can be a bit dense. Scala.js is great, but it is different (numeric primitives, threads, to start with).

philipkglass 10y ago

Scala was my first serious use of a JVM language and I kept hitting little rough patches that people were assumed to understand from a prior Java background. One example: a month or so into my use I started getting a puzzling failure when sbt was trying to download a dependency. Everybody already knows about Java's security certificate handling, Ivy, and Maven, right? I didn't. I kept on Googling the wrong terms because I was searching for Scala and sbt. The problem turned out (IIRC) to be a dependency download attempt that started from a URL whose certificate was trusted and then got 302 redirected to a mirror whose certificate was not yet trusted by Java. The error messages that actually showed up in my console were not at all helpful and I ended up using tcpflow and a Java-savvy colleague to figure out what was actually happening. Would it be so hard for (e.g.) sbt to provide an interactive security prompt for if you want to trust a remote source's security cert, rather than expecting you to figure out the error message and solve it the Java way with plain Java tools? (Maybe it would be hard. Maybe that's why it doesn't do that. I don't know because I didn't use Java before Scala.) I don't have concrete examples to hand for the other rough spots but I recall hitting other areas of knowledge that are explained via Java instead of standing on their own. "The Scala Bar is like Java's Foo, but with these improvements..." I never learned the Java Foo and I don't really want to have to acquire a working Java developer's knowledge to use Scala. I'm using Scala and not Java. If you're writing docs for Scala and the reader needs to know something important about either Java-the-ecosystem or Java-the-language, please inline that knowledge.

lmm 10y ago
I wouldn't recommend SBT, especially for beginners (Maven is much better documented), but no, it can't give you a prompt because programs don't have access to modify the keystore by design. The JVM is one of the few platforms that actually has a decent go at security, which sometimes means usability suffers.
- jackcviers3 10y ago
  To use scala effectively, you must use SBT. Almost every scala library and framework is built using it. There are tons of productivity enhancing tools wrapped in plug-ins for it. It is java, scala and scalajs aware, and incrementally compiles large projects if you use it. The documentation for it is good from version 0.12 on. You can learn 90% of what you need to do scala builds in SBT in 4 hours by reading the documentation and the walk-through tutorial. Eventually you may need to write your own tasks, but 90% of those tasks are covered by the existing plug-ins available, and you can easily modify or create a new task by writing some simple scala function on your first day using the tool without having to publish a plug-in to some repo for it to work. I absolutely would reccommend SBT for beginner scala users. It's a must to use and understand it, as much a part of understanding scala as understanding for comprehensions, case classes, and if/else expressions.

bsder 10y ago

Excellent. I can now point to this for a good objective reason to not use Scala. Actually, I'm really sad. I used Scala back in 2005 (Edit: Corrected from 2001?) (God, I'm old) for it's Actors model to do peer-to-peer networking protocols. It was SOOOOOO much better than C/C++ and I could deploy stuff without installation across multiple architectures. I'm especially sad because it seems like Scala always needed just a little more sustained effort on the community front to move into the big time and it never really got it.

hocuspocus 10y ago
Scala came out in early 2004, Scala 2.0 in 2006 and I'm not sure about actors but probably not before 2007. In 2001 Martin's lab was probably working on Pizza / Java generics :)
- bsder 10y ago
  You are quite correct, I just looked at one of the domains I registered for that and the date was 2005. As for actors, I was definitely using alpha level stuff. So, your dates jibe with that. Apparently I'm getting old enough that my memory is getting faulty. :) Now, if I could only figure out how to do strikethrough for edits...
yawaramin 10y ago
I wouldn't be that sad. Bad docs may be a good objective reason not to use Scala, but there may well be even better objective reasons to use it, like doing data science with Spark, or even building resilient fault-tolerant systems with Akka. The final calculation will, as always, rest with each potential user.

Fiahil 10y ago

I write Scala code professionally, and the language documentation is the worst I've encountered. Luckily, I've leveled-up to the point where I don't need it anymore and can just lookup prototypes and comments directly in the source code when I need it (thing almost everyone is doing after a certain time, btw). I understand the frustration of beginners, and I've even began to host talks/presentations, inside my company, for a few coworkers. I hope to get them past, at least, past the few interesting concepts and the shitload of symbols/operators/random-combinations-of-chars-on-my-keyboard that you encounter on a day-to-day basis.

cle 10y ago
This is not an excuse for poor documentation, but I've found that not relying on documentation in general vastly improves my productivity. It requires being comfortable digging into the innards of the libraries and frameworks I use, which helps me understand performance characteristics, extension points, understand stack traces, understand failures when they happen, find bugs, learn language idioms, etc.

allengeorge 10y ago

I am completely unsurprised. I've been pretty negative on Scala in the past, and this is one of those reasons. The community does not feel inclusive and, my perception is that as a beginner you're simply expected to deal with the lack of documentation, the odd behavior of the tools, etc. And that (frankly) makes me fairly uninterested in contributing back to it. I wonder if it's because many people who stay with Scala are more interested in the many advanced language features it offers, as opposed to building libraries to be used by day-to-day practitioners (who have very different metrics for deciding if a library is worthwhile or not).

runT1ME 10y ago
I'm not sure what you mean by building libraries to be used 'day-to-day'. If you mean that the Scala community is in general more interested in building libraries/tools used by professionals than hobbyists I'd agree, but I can't think of any popular libraries that aren't used day to day by all of the developers on our very very large scala team.
- allengeorge 10y ago
  Out of curiosity, which libraries does your team use?
  - runT1ME 10y ago
    Scalaz, Scalaz-Stream and http4s constantly. Doobie, Spray, Shapeless, Monocle, and others less often but still definitely more than rarely.

ape4 10y ago

How about the speed of the compiler? Last I used Scala, that was the deal breaker for me.

petetnt 10y ago

I dove deep into Scala a short while back and I can concur with those that thought the documentation was sub-par almost all around, from Scala-Lang site itself, to big things like Play Framework to across small userland libraries. The saddest thing was that I wanted to improve those docs, but I didn't know how. When I finally got to the point through tedious trial and error, I couldn't even remember where to start. It doesn't help that there's 10 ways in Scala to do everything, but no way to find out which is the best one, or the worst, or one that even just works with your current version. Surely this the tone of this post is quite whiny, but it really did make Scala hard as hell to approach.

cutler 10y ago

Scala's poor documentation stems from a much more fundamental problem - the absence of a Clojars/Rubygems/PyPI for Scala libraries. It's in the process of being fixed now, I believe, but why did it take so long? The Clojure community has a much lower profile in industry than Scala yet right from the beginning they really valued their community and produced an excellent repository for Clojure libraries and an easy-to-use build tool - Leiningen. The Scala community, by contrast, comes across to outsiders as just not that interested in community. Maybe it's the Java legacy.

philipkglass 10y ago

I remembered another thing that Java users already know but surprised me in Scala in a bad way: null. I read a lot about Scala's type system in the week between I was hired to write Scala and when I actually started writing code. Most of it was about how great Scala's type system was and how much safety it provided; the company even called itself Typesafe then. I read many paeans to the virtues of Scala's type system that would turn runtime errors into compile time errors, but they didn't highlight that it can't prevent that most common and annoying of Java runtime errors, the NullPointerException. Due to a lack of prominent mentions in the Scala docs and tutorials I read, I thought that Scala authors either didn't have to think about Java's Billion Dollar Mistake or that the compiler would guide them to safety before the code could blow up at runtime. Maybe manually dealing with nulls is supposed to just be assumed by anyone using the JVM... But I'd used Jython a little in the past and I didn't have to explicitly deal with null-checking then. Jython converts null to None. In the absence of prominent warnings to the contrary I had thought that Scala would provide at least as much automatic safety as Python-on-JVM does.

aianus 10y ago
The correct way to handle this in Scala is to wrap the possibly-null reference (which I assume you're getting as a return value from some Java library) in Option(), not manually checking for null.
- philipkglass 10y ago
  By "manually checking" I mean that I have to use my own brainpower to notice places where null can leak in to code I'm writing; the compiler doesn't actually enforce the type safety I thought I had. I do use Option to handle sometimes-nulls after I notice them. EDIT: since Jython doesn't allow raw nulls to leak in from Java libraries, and Kotlin prevents accidental use of nullable values at compile time, it naively seems like Scala could prevent accidental null introduction despite living on the JVM. Or as a distant second-best, prominently warn about the perils of null whenever introducing its type system to beginners.
  - 10y ago

jomamaxx 10y ago

A production is only as good as it's training and docs. I would go a step further: 'Training and Docs ARE the Product'. Having bad docs is like selling a car without wheels -> It's not a car :), rather, not a thing that 'solves the problem of getting people from point A to point B'. My experience with Scala has generally led me to concur with the overall assessment that Scala information and communication is pretty weak. Hope they can improve it, it's a pretty cool language.

horusthecat 10y ago

I really wanted to pursue Scala. It looked promising: runs on the JVM, is far saner than Java, has features that keep the "Java 1.4 was the last real Java" crowd away, has a mixed-paradigm OO/FP approach, lots of features... things like all the FUD over compile times and performance didn't really bother me (if I cared about resource usage/performance, I wouldn't use the JVM, duh). I found two classes of problems. The first was the lack of practical guides. How do I access a database? Should I use a Java lib for that? What about a rudimentary CRUD app? What if i need something Java-EE-ish, like a message queue/IPC? I kept finding myself in scenarios where I had to reach out to Java, which I was deliberately trying to migrate away from. Second, there's the fact that Scala has full OO along with the ML-style FP, which makes it hard to figure out if I was doing things the "right" way. Do i use traits and composition and case classes? Should methods go on classes? What's up with the Object pattern? Do I store state on classes or should I prefer case class/record types? When is it a judgment call... and if it is a judgment call... how do I make it without much experience in the language or having any experienced Scala users to guide me? I'm not averse to spending $100 on books and working through them. I tried that with Scala, but somewhere around page 200 of Programming Scala, gave up. Then there's the scare factor, there are so many "we're switching from Scala to Java 8" or "we already use Grails" that it was looking like it was turning into a dead end professionally very quickly, especially outside of DC/NY/SF/Chicago. One job I was looking at told me they were moving all their Scala work into Java because of client pressure. The bigger irony being that I started using OCaml instead, a language where the documentation is usually just an interface file and type signatures.