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.
Allow Comments
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.
Broken information
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
Thanks.