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.
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
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.
Look at the number of contributors for Scala , Go , and Rust .
>> number of contributors is probably a reasonable indicator
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.
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.
Could be because Gradle up to version 2.x provided only Groovy for writing plugins and build scripts. Gradle 3.0 was released a few months ago, and provides both Kotlin and Groovy for plugins and builds, and even prefers Kotlin for writing plugins. Perhaps the "not-so-perfect" situation will change as plugin providers switch over.
I recently looked into Groovy's apparent popularity at #17 on the TIOBE ranking and found Baidu was giving a result 12 times too high and Yahoo a result 20 times too high, both of which would skew the ranking. Groovy's real ranking is somewhere below that of #50 ranked Clojure. These results are being used to promote Groovy as successful to the Apache Software Foundation directorship. I can understand Gradleware wanting to switch to a language with a seemingly more honest approach to promotion.
Joking aside, in Clojure this a feature, one of Clojure's theme is "embrace the host"(leverage java apis).
I don't know Scala but in Clojure you definitely need to become familiar(if you aren't) with Java if you are serious about writing productions apps in it.
Also, abstractions leak.
You needed to dive into Java to figure out something as basic as parseInt?
(.parseInt Integer x)
That may be what he means by dive into Java.
On the JVM, even if you stick to pure Java, you still need to figure out where and how the dependency resolver is launched before you can override its settings, which can depend on things like your build tool and IDE. But at least, adding your own certificates to the keystore/truststore is fairly straight-forward.
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
My team at Lightbend is responsible the majority of the Scala 2.x compiler and standard library work. That's our focus. We do try to help out on the documentation front over at https://github.com/scala/scala-lang. You can easily see for yourself that 90% of the PRs there get merged.
Don't boo -- submit a PR!
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.
My experience at the office is different. I come from Java, but I've seen people who literally never programmed in Java or any other Java-like language succeed with Scala (and then they get horrified when they find out what Java looks like). They have none of the bad habits that come from years of writing Java code. It's enlightening, really. A few years ago this experiment wasn't possible -- of course everyone doing Scala was a Java expat. Not anymore, though!
I couldn't disagree more with you about excluding people. Excluding newcomers is always bad, but also, don't people "comfortable with advanced programming" deserve good documentation? Of course they can and will succeed in the absence of it, but only after wasting valuable time.
Linus' statement is controversial and shouldn't be quoted as gospel. In any case, he argued against C++ programmers because he thinks they -- and their chosen language -- suck, not because of advanced programming or whatever (note: not my opinion!).
My personal experience has been that it is easier to explain people Scala when you can explain it in Java construct terms... But I can see how someone coming from, let's say, Swift, can have an easier time writing idiomatic Scala.
I am against excluding people for the sake of excluding people but you need to consider that communities have some core values, and the core values behind the Scala community are different to that of, let's say, PHP. You know what I mean.
Also, it'd be VERY disappointing if the reason for this lack of documentation was the explanation from the root comment in this thread.
My whole team has worked extremely hard this year to bring you the best 2.12 compiler we can. We also spend as much time as possible helping out with polishing documentation, but we feel a coordinated push for better documentation belongs under the umbrella of the Scala Center (whose mission is to "Independently guide and support the Scala community" and to "Provide deep, and quality, educational materials for Scala"). We'll be thrilled to collaborate, but we (as veteran Scala users) are not the best placed to write getting started guides.
EDIT: It was brought to my attention that my comment about the Scala Center could be misinterpreted. I meant to say I would support a proposal to the Scala Center advisory board about improving Scala's documentation, with a focus on the getting started experience.
Calling grouped on a Seq.
I've been playing around with some API requests, and needed to batch a long Seq to make reasonable sized GET requests.
So I called grouped on a Seq, then to sanity check I called .length on the grouping.
Then suddenly I had an empty iterator.
Maybe I should have known better, yeah, but the documentation I was reading http://www.scala-lang.org/docu/files/collections-api/collect... doesn't mention this fact about iterators. Again, maybe I'm the only person in the world who didn't realise the problem with calling .length on what I thought of as a regular old batched set.
It wasn't until I hit on the right google combination that I found http://www.scala-lang.org/api/current/#scala.collection.Iter... from a stack overflow reference, and the lightbulb finally went on.
By core values of the Scala community I refer to trying to create idiomatic ways of solving problems, and trying to get the most out of the language. One evidence of this is the amount of domain specific languages created in Scala.
Twitter's Scala school was a good resource for me, the official tutorial by Odersky in Coursera is a good starting point too. You can also watch Scala talks in YouTube, to supplement documentation reading.
I understand what you mean by core values. I don't understand how they are improved by a lack of documentation.
Also, I think it attributes the bad documentation complaint to the wrong thing.
Look at the tutorial, for example: http://docs.scala-lang.org/tutorials/tour/tour-of-scala
The intro page just lists a few selling points: OO, functional, static typing and extensible. The second page has no continuity and is about "Unified Types," with a big complicated diagram and a blob of code. No explanation what to do with the code to compile it, run it, load it in a REPL or anything. I need a tutorial just to be familiar enough with Scala to use the tutorial. The entire "tutorial" is like that with no continuity and no connection with anything coming before it.
A person can go to haskell.org, navigate to the documentation, start with the tutorials, and eventually learn the language. That would be nearly impossible using the scala-lang.org page, without a huge amount of pre-existing Java and functional coding experience.
"if the only benefit of using Java was excluding Scala programmers, that was enough of a benefit."
Scala adds multi-paradigm heavily complexified syntax on top of Java.
Scala : Java :: C++ : C
well I was scared about that as well, but than I bought
and used cats (XorT,OptionT) and now I don't want to miss those two.
P.S. I am not gifted also and I guess I managed to learn it to an extend, too. Basically I'm always afraid when writing mutable/imperative code now.
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
"- [..] 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."
Keep in mind Scalaz is not Scala.
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) 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.
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).
I'm not sure if you are serious? Spring's documentation is some of the best I've ever seen.
Eclipse through the maven plugin (m2e) will auto download the source code and will show doc as you code (along with drilling into the code. Intellij does something comparable as well. Racer can do this as well (and I admit far nicer in that it is editor agnostic).
The problem is the tools for Java/Scala are all over the place so developers have different experience with the language that probably have very little to do with the language itself (syntax and libraries) but rather the tools.
I would agree Rust is not the norm and IMO perhaps even the gold standard of what modern language organization and tooling should be.
Java/Scala should probably have better builtin tools (or atleast mutually agreed on tools like auto formatting, editor agnostic completion /refactoring (ala racer), package management (Java is actually decent on this as maven is the standard), etc).
EDIT: small grammar error
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).
The Markdown-renderd docstrings for modules and functions can be converted into nice websites or are available in the command line.
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.
In 2001 Martin's lab was probably working on Pizza / Java generics :)
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...
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.
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.
Until that happens, in Scala we continue to work through in the presence of potential nulls by wrapping stuff that comes from Java APIs in `Option`s and never explicitly returning `null` from any Scala APIs.
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.
Scala.js is great, but it is different (numeric primitives, threads, to start with).
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.
Java:Scala job ratios in other countries are even worse:
So I think it's fair to say that, with the exception of the London financial sector, Scala hasn't really made a difference to the dominance of Java in industry.
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.
Erlang has a kind of narrow use case though. It's pretty much only useful if you really need the low-latency high-availability actor model. It's amazing for that but not for much else. Elixir fixes some of the warts, though. Scala is a truly versatile language, being able to replace Python, Java and Erlang, and inheriting most of the strengths of those.
Btw, Scala has all of the major concurrency primitives (STM, futures, actors, mutex etc.) and doesn't dictate you use any of those.
Going from Java to Clojure requires a major mental shift :)
The problem is that I can program Java as Java++.
Java 1.8 still has its warts, but are they worth the shift to Scala? Maybe? But it would really have to be a compelling reason.
For example, people still often don't know about java.util.concurrent. 99% of their concurrency problems could be solved simply by grabbing the correct data structure out of there.
If they can't be bother to know something as easy as that, what real hope do I have of them really using Scala well?
Oh, yes. Few who've had to deal with both a Java 8 and a Scala codebase are going to tell you otherwise. Java 8 is like Scala through blurred glass.
Another thing is that Java 8 is Java++ only now, after many of us have already adopted Scala. In other words, "too little, too late" :)
Regardless, are we discussing whether it's good idea to adopt Scala coming from Java (I think it is!) or whether the transition from Java to Scala is easy? I thought it was the latter, and if so, it's unarguably easier than the transition from Java to Clojure. Scala "looks like" Java in a way Clojure doesn't.
A bit of both. How's that for a hedge? :)
Admittedly, I'm coming back into Java with 1.8+ and don't have a legacy codebase to deal with. So, my calculation as to whether Scala is worth the cost is quite skewed from someone who has been doing it since Java 1.4.
Is it easier to transition from Java to Scala than to Clojure? Maybe. But the people who can make the Scala transition also seem to be the same people who can make the Clojure transition.
And, I think that's the core problem for Scala. The features that make Scala compelling aren't a nice, slow, logical evolution from Java.
My introduction to FP was via Caml Light, SML and Lisp, so either Scala or Clojure are approachable to me.
I don't use any professionally, as our customers only do standard Java and C# projects, but among the programming languages I dabble when travelling, I tend to play more with Clojure than Scala.
Since I have always worked in companies where you don't get through HR without a degree in computing related areas, I always ended up working with Java developers that do know multiple programming languages.
But I guess it is indeed a problem for those that are self taught.
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
Note: Enrolling in the courses individually is possible for free, going through the "specialization" page at https://www.coursera.org/specializations/scala only shows the for-pay option.
However, the follow-up courses, Reactive Programming (retired) and Functional Program Design, are a total let down. They are a rip-off, especially if you paid for them: a complete mess, no relation between lectures and assignments, no introduction of new concepts in relation to a greater context, the slides are not proof-read, constant mentions to non-existent slides and lectures, repeat material from previous courses (a side-effect of the courses being mash-ups of previous material), and example code that doesn't type-check or compile. It's not any single mistake, but the aggregation of them all, and the feeling that the authors just don't care enough. Thankfully I didn't pay for this.
In my opinion, the gold standard for Coursera is Dan Grossman's excellent Programming Languages, which I fully recommend.
The coding tasks could have been okay - if there was any guidance. I don't even get to see any sample solutions. So even if I make it work, I don't know if that is a good way to do it, the "functional", the "Scala way". And the performance issue I mentioned, it was a major one, the difference between the code even being usable for more than a thousand elements in the list or getting a stack overflow, and the difference was extremely minor, in one case the order in which you called "union" on sets. All of that had to be found out by the students, and even after they found out nobody really had a good idea or explanation for why it was so.
Also, there only was one (small!) opportunity to actually practice what you just learned per week - and that came without any feedback apart from "works/doesn't". Since the course was about a particular programming style that really wasn't enough.
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.