Agreed. However it’s been pointed out that it also needs to be made official. Unless Scala is officially supported and marketed for JVM, Android, JS, and Native, Kotlin has a big advantage over us.
I’m all for getting official support for Android and Native (assuming JS is already “official” isn’t it)! How it would be funded on the other hand I don’t know…
I would prefer to complain about kotlin. Why they have made more better language for dsl. My life would be more pleasure if they had not made scope and reciever functions.
Before I write this story, let me say I am willing to help with the documentation and will try to contribute soon. Please listen and take this with a grain of salt as constructive criticism coming from a person new to Scala who has learned ~ 7+ programming languages over the last 10+ years, Java 1.4 being the first which I taught myself.
This is my perspective as a new user to Scala.
I chose Scala not because I thought it would be fun or cool to learn, but because of AKKA, KAFKA, SPARK etc. and the fact that I spent over a year researching and designing a new app that is very complex and needs these tools. I had not really even looked into Scala until reading Designing Data-intensive Applications by Kleppmann while doing research on how to architect the app. I could have used Java (it’s ironic I am verbose but hate java), but it is so verbose I could write 3 books before finishing the app. I looked at RUST, GO, KOTLIN and more before choosing Scala for this project. So it is purely out of necessity that I am learning Scala.
I know a lot of people complain about the documentation, for many reasons. I really feel that improving the documentation in the following ways would help in getting more people using Scala.
Label the Documentation
When I type PHP Documentation into google the top link is directly to the documentation. When I type Scala Documentation into google the top link is to a page on docs.scala-lang.org which has links to this, that and the other, which one does a new user choose since none say Documentation? Tour of Scala is the closest I have found to documentation. The tour of Scala needs to be renamed “Documentation” to make it clear that is the documentation. This frustrated me beyond belief when first trying to learn Scala. I kept searching google for Actual documentation, I kept saying this can’t be the documentation it is too light, where are the facts.
One of the best things about the PHP documentation is it lets users comment directly in the documentation. Allowing users to communicate directly in the documentation allows them to share their findings with other users, thereby saving other users COUNTLESS HOURS OF SEARCHING. Many pages of the PHP documentation have tons of relevant, helpful comments. Check this out PHP documentation Look at all of the user contributed examples in the comments. Notice how users inform other users of things like changes between PHP versions etc. This style of documentation saved me countless hours while learning and working with PHP.
Sure comments would need to be monitored, but is that anymore work than viewing a pull request? Also people use links to these in there resume, like they do for stackoverflow questions.The best thing about allowing comments in the documentation, is it allows me to go to a part of the documentation when I am having an issue or want to use something new, and I can quickly see others have had the same issue and find an answer more quickly than having to google and dig. Maybe allow users to login via Stackoverflow in order to comment, this would tie into their real world reputation and help prevent many garbage comments.
Give us the Facts
With Scala it is not just the fact that the syntax is complicated and you have to learn many new concepts, it is that the beginner is left searching and googling and digging for answers to the point you keep asking yourself WTF am I even doing this for??? When you are not given the facts about the structures of a language upfront it makes it way more confusing when you see people using them in code and examples you see later. Hence people complain about the complexity of Scala syntax. It’s kind of like teaching kids words, but not teaching them how to structure a sentence. Then throwing them a book and saying “here you know words now read this book and write a report”.
What are the facts about Traits, where are the facts listed. I don’t want to waste more time digging while learning! The Scala tour only gives a brief overview. For example I think much of what is Alvin Alexanders post should be in the Scala documentation itself Traits simple information like this " In a trait, define a field with an initial value to make it concrete, otherwise give it no initial value to make it abstract:" Basic facts about the language like that should absolutely be included in the documentation. I am willing to help add this information as I get time.
The getting started with Scala and Intellij guide didn’t work for me, there are missing steps. If you miss a step then there is no option to create a Scala Class listed in the IDE drop down, which requires more googling to figure out why? You have to add Framework support and something else I’ll have to dig back into it, I’ll figure it out and do a pull request for the documentation.
I remember reading the Odersky Programming in Scala book using vim and the command line, that worked pretty good. Then I got a big surprise when trying to do the Getting Started with Scala IDEA and had to spend a good bit of time figuring out what the problem was, why no option for Scala class or package. It is a small thing, but in the end it is the small things that give new comers their first impression.
I know this probably sounds negative and critical, but I really feel this is why Scala is not more popular. It’s not the syntax as much as it is the lack of Information that is so frustrating to me and I can’t be the only one. I know from reading online that many people complain about the documentation. I have a feeling the docs are light because adding to them takes time and most people who are donating their time to the docs are busy with a life and work. Also documenting something can be harder if you already know it than if you don’t, because it is easier to leave out steps and pertinent information.
I’ll do a pull request soon with changes to the Getting Started with Scala in Intellij first. To a new user it’s discouraging when you can’t even follow a Hello World example and see something work. If trying Scala in Intellij from that link is the first thing a user tries after learning Scala from the command line or it is their first time experimenting with Scala then they get discouraged.
I like Scala. I love it’s capabilities, it’s power and even it’s quirky complexities. I like that it allows OOP and Functional programming to coexist. I’ve actually been printing the current doc pages and making notes on them in binders. I’ll try to start contributing to the documentation where I can as soon as I can.
Open Source Projects
Another thing I think that helped make programming languages like PHP so popular was all of the small open source projects people created such as Wordpress and the many open source social networking apps like elgg etc. I have not googled and have only been learning Scala a few months, so I have no idea if there are any such current Scala projects around. What happens is small time developers see an opportunity to make plugins for these apps and sell them on websites like HotScripts or Envato. So putting out something such as a simple open source Social Network written in Scala would bring much interest.
As a web developer I was surprised how easy the Scala Play Framework makes creating an app. I’ve been amazed at how much I can accomplish with so little Scala. In ways it is easier to create a Web App with Scala/Play than with PHP/OtherFramework. Not having to install and configure a separate web server with Play Framework is a huge BONUS.
The base of my app is a social network. I am considering releasing that base as an Open Source project to the Scala community. I think having a large example of a working app that people can inspect will help them learn Scala much more quickly. The reason I chose Scala for this app is because the tools like AKKA, KAFKA will allow me to code the app in a nearly 100% modular fashion much more easily than other languages and even add capabilities not imagined. I like the DSL abilities too.
I’ll start trying to contribute to the docs soon. It will probably take a few months, but I am determined to release an open source social network. Something super basic other people can add to and improve etc. Something that gets a community of new people involved and generates interest.
If you read all of that God bless your heart, I am sorry. Remember Java is too Verbose for me. LOL
Actually, while I think you’ve identified a problem, this is exactly not the solution. The Tour of Scala probably ought to be labeled something that makes it sound less like “documentation”, because it isn’t – it’s a fine high-level overview, but is quite incomplete, and isn’t trying to be otherwise. It’s intended to be digestible, not comprehensive. My experience from helping folks on the Users Forum is that people tend to think the Tour is the documentation (and is therefore reasonably complete), and wind up pretty confused as a result. Putting the label of Documentation on it would, I think, make this far worse.
The thing is, there isn’t official public documentation for Scala in the sense that you are looking for – as far as I know, it doesn’t exist. There is the spec, but that’s basically unusable for most people. And there is the book Programming in Scala – which is in many ways the actual documentation (reasonably clear and complete, and written by the right people), but it’s not a free website.
That’s not an unreasonable state of affairs, nor an unprecedented one (for instance, the documentation for the C language was, for all intents and purposes, Kernigan and Ritchie’s book), but I think it may be contrary to current expectations. I’d say it’s worthwhile for the community to think about this point…
Bajillions of them, actually, but you may well be right that they’re too hard to find.
If you haven’t come across it already, I commend Scaladex to you – that’s the fairly-complete index of open-source libraries in the Scala ecosystem. That’s a step in the right direction, but AFAIK it doesn’t cover the open-source applications written in Scala, of which there are probably far more. I’m not sure the community has ever considered a similar index of applications, but it’s an interesting idea…
On difference being that “Programming in Scala” is about three times as long as “The C Programming Language”.
The EPFL and Scala Center have been supporting the learning of Scala through both the Coursera courses and the Scala Bridge program. These probably aren’t as well publicized.
A lot of people, like Akashicseer, rather than learn Scala from the beginning and from a clean slate, have to learn Scala in a specific domain (Spark, Akka, etc.) where they need to self-learn and struggle to independently piece together their Scala knowledge.
Coursera courses and Scala Bridge are good for beginner knowledge, but may lack the intermediate or advanced knowledge needed for large projects that Akashicseer testified to.
Finally, the Scala Center redesigned the Scala site(s) a few years ago. It helped better organize the content, and this has resulted in a lot of contributed improvements. However, it could always use further improvements and better organization. Maybe the “Tour of Scala” shouldn’t be called “Documentation”, but its evidence that it is getting close.
I’m afraid people will spend too much time arguing the narrow issue of whether the “tour” should be called “the documentation” or not. For larger context to the discussion, here is the hierarchy of the site(s):
Home page (which has “Scala in a Nutshell”):
I think more killer libraries or frameworks will help a lot:)
Well that is certainly discouraging. I was willing to help with what I thought was documentation. No wonder one of the biggest complaints about Scala is the lack of documentation, it literally doesn’t exist. I wonder how many of the languages in the top 20 TIOBE don’t have official documentation? My guess is probably 0.
Why doesn’t the Scala community want to listen? This post is nearly 3 years old and nothing has changed. That makes me not even want to waste time trying to help anywhere. I investigate before I spend my time and the facts so far tell me not to invest.
Now imagine I tell someone that Scala doesn’t have documentation because you are expected to buy a book. I have the book and like it, but it is not official documentation it is more like Scala tutorials explaining the language clearly. I actually started looking for the docs while reading the book. Alvin Alexander has the best books I have found so far. That guy is brilliant, he breaks down the information, Functional Programming Simplified really digs into Scala Functional programming with almost 800 pages of short 1 to 5 page chapters. May I ask a question? Do people have to buy books to learn the facts about Java or does Java have great documentation? Here is a Bonus Question! Did lack of documentation get Java to #1 in Tiobe Index?
Why not have Documentation like Java? It seems people want to help with documentation, but get discouraged when they realize no such thing exists and no one wants to improve the tour.
I was going to try to contribute to the documentation but now I see that the documentation is not meant to be documentation at all.
Also if the tour of Scala isn’t meant to be the documentation but a quick introduction or whatever it is, why not have an Actual Documentation which built off of that Tour and put links in the Tour to the Documentation which expands on the Tour. Why not have documentation like Java?
Maybe rename the Tour of Scala to Scala Overview and the thicker documentation as Scala In Depth. Like take the current Tour Documents and add more Facts and information with small examples. This way people could read the Tour docs, then get more in depth documentation on the specific information right there no searching google needed. Hell you could even give a link to suggest books that cover whatever piece of information in more depth at the end of the in depth pages. Seriously the one thing I learned most while tutoring, is people get frustrated easily, they want answers ASAP. I even told many that if reading was not their thing, then IT was the absolute wrong field for them.
Maybe it would help to think of Scala Documentation as "Highlighting Scala’s Features"
Now wouldn’t you want to highlight all of the cool things Scala can do? Wouldn’t it make more sense then to Highlight the power of Scala’s Case classes and when to use them and not to? Or that you can use more than 1 trait with the keyword “with” that is not even in the Tour.
Also having the tour but not having official documentation, at first gave me the impression that the Scala Community is small or shrinking. I googled “Is Scala Dying” Then I went to the Tiobe Index, uhg only 31, Scala is the first language I have bothered with that is not in the top 20. Then I made sure Scala was at least 10 years old. I didn’t want to start building an app with a dying technology. Then I googled “does anyone use Scala in production” Not sure if Twitter still does looks like they went to Java. How many Scala Developers are there? Is the number growing or shrinking?
I’m a very intelligent person who likes learning and has learned many languages and concepts. I literally live in a small library of hundreds of books about Comp Sci. But imagine if I were some sort of project manager, lead software engineer, small startup etc… Someone who didn’t dig as deep into the projects needs as I did, who doesn’t see the value of Scala for distributed computing. Those decisions are being made daily. Scala could be chosen but often it is not.
Documentation is a language feature as much as a data structure is, document the structures, highlight the features.
So having a Lack of documentation can give users a lack of confidence in Scala from the get go. I was really hesitant before choosing Scala. If not for AKKA, KAFKA, SPARK and a few other reasons, I would have placed the Stairs book on the Shelf and moved to another programming language. Python, PHP and Java were runners up and Python may still be involved for some of the image AI processing.
I have a real interest in trying to make Scala more popular. Scala is a great language with so damn much potential. Also why not allow user comments in the Tour? That could help tremendously and maybe even eliminate the need for in depth documentation as it would let users comment below the official area of documentation. That worked very well for PHP it created a feeling of community, it made it feel like you could easily get involved and like php was exploding in growth. 9/10s of reality is Perception. It is part of human nature to want to be a part of something larger than yourself. If people perceive it as being too hard to become part of a community then the reality is they won’t try.
Is the reason for lack of Documentation an attempt to make money by selling courses and books? It doesn’t even make sense that that could be the case. Couldn’t you make more off creating a very popular language and then consulting, writing books, creating courses etc.? Could one really believe that they wouldn’t be able to sell books and learning materials by keeping the facts hidden? I really want to believe it is because no one has had time to create the documentation. Scala is so complex you would need books and learning materials even with in depth documentation. So I can’t see this as the reason. Anyone know the reason for no official documentation?
Exactly!!! Hell one more good framework and Scala might jump into the top 20 languages on TIOBE TIOBE INDEX
No troubling docs needed
I agree that a comprehensive online “book” with the same level of detail as “The Rust Book” or “Programming In Scala” is essential and that it looks kind of bad to not have one. I also like the suggestion to have comments in the docs.
I was just looking to see if StackExchange or Github had an API for apps. If so someone could create a comment system using that, to allow users to login and comment which would greatly reduce the likely hood of spam comments as people could reference them in their resume’s.
Scala is a complex language, so out of all languages, it would by far benefit from in depth Java like documentation.
I like the Programming in Scala book but documentation it is not. It is a great book to learn the basics and is full of facts but it is in no way a replacement for true documentation. I need a quick easy searchable way to find information about things like Traits for example. Plus my desk is small I already have 4 scala books on it and notes and other stuff, I have to look over to see the monitor.
So I love Scala, I just hate the lack of documentation and it seems no one cares. Alvinalexander.com is the best resource of facts I have found yet. I don’t waste time on classes etc.
I have not seen comment sections in other languages, just PHP, but it was one of my most favorite time saving features.
For a long time, the Scala site used to allow comments using Disqus. It seemed like a lot of work to maintain. There was an experiment to move them to Discourse, but it didn’t work out for a number of reasons.
I’m sure a proposal to use a different comment system would be entertained.
Yeah disqus has no real world ties into anything so random people from random places can troll and comment. Something more personalized would be needed. Maybe a system where people login with their Github account. Then the system needs a minimal admin panel and a reputation system. Without a reputation system and admins it is a free for all and arguments etc become a plague. It is work for sure. But it would be worth it in the end for the community. Either that or real documentation.
I can vouch for that.
I don’t think we should add a comment system of any kind, tbh, but perhaps the site could do a better job of directing people to places they can ask questions and discuss things. Right now we just have the “Problem with this page? Please help us fix it!” link, which is a good start, but maybe we could also link to https://scala-lang.org/community/ , something like that?
Please don’t be discouraged! More/better/polished documentation is crucial for Scala’s continued growth. As the Scala team lead at Lightbend, I commit my team’s help to make sure nothing stands in anyone’s way when working on the docs.
I can’t speak for others, but my team is very busy with PR reviews, bug fixing, implementing the roadmap. Unfortunately, that leaves no time to lead documentation efforts, but we are always happy to help where we can for documentation.
I am working on writing up our plans for 2.14 this week. One related topic that I will explain in more depth there, but I want to already mention in this thread is that we plan to reserve the summer for improving the newcomer experience and overall polish, before we switch full-time to core 2.14 development.
I think here is a good example which demonstrate that standard documentation is hard to do more friendly.
Also I think that there should be clear facts where scala is just the best.
Some time ago it is was absolutely enough to say:
- string interpolation
It seems for me that scala take inspiration in big data processing
It can be undeniable fact.
But I really do not understand how the language can be the best in data processing until it does not have the best intergration with data bases, for example one of the next our most desirable features is better sql intergration.
It is very sad that we do not have tools to make the best integration:
- simple fast anonymous pojo, or named tuples(something like named arguments which is also available in sql libraries[slick] )
- external preprocessors for language injeciton
Our average table has more than twenty columns. Sql integration and queries are a headache for us.
See also: named arguments in pattern matching
IMHO: Named access in dsl is a killer feature.