In my master thesis about writing a CI/CD tool to test release upgrade and downgrades, I introduce different Erlang OTP concepts so the readers and my successor can understand what I am talking about.
My thesis supervisor suggested to also include a section about frequently seen difficulties when using Erlang OTP as a beginner. I think that including the community’s opinion and feedback about this matter would be beneficial to the readers, so, if anything comes to your mind, please feel free to reply to this post .
To give some example of difficulties I have personally encountered or heard:
Understanding the difference between a module, an application and a release
Understanding why SASL is required to perform a release upgrade/downgrade
Building a release
Building an upgrade/downgrade (appup, relup, performing it, …)
Thank you in advance for your replies,
Have a nice day/weekend !
Seeking a function to do a task I read the manual.
I may find a function whose name suggests it might work. While the description might sound encouraging, few functions have examples of its usage. Seldom in the documentation is mention made of use cases for some modules or how best to employ most functions.
A welcome exception is Dan’s wx:demo().
Perhaps some modules were introduced as a result of a thesis?
I have a vague memory of once finding a link to such an original document.
In summary, as an Erlang beginner my biggest difficulty is limitations of the documentation. No doubt, this is in part due to the size of our community.
A vicious cycle, perhaps?
After quite a few years as an Erlang trainer I can tell you that all the items in your list, in my mind, are not things newcommers usually struggle with. I mean, a developer can work in Erlang for months (maybe years) without even thinking about releases, SASL, etc.
Not to mention appup, relup, etc. I’ve been working with Erlang in production for almost 2 decades and I’ve never used any of that.
From my perspective, the problems newcommers face are more mundane. The popular ones (once again, based on my experience teaching Erlang in different places and platforms) would be:
Understanding strings as lists of chars (Why [50, 51, 52] == "234"?)
Exiting the Erlang shell
Understanding ignored variables (Why they should use Name instead of _Name).
Understanding behaviours, both in terms of using existing ones and also in terms of defining their own. Understanding why they are not like Java interfaces.
Understanding try…throw…catch…end and why that’s not like throwing and catching exceptions in other languages.
Learning how to use pattern-matching in function clause heads as a mechanism for flow control.
Finding good documentation with examples for basic functions (like @kanga-roo mentioned).
Finding and using development tools (e.g., a formatter, a linter, etc…) since there no official ones.
This is a sign of the times. Today, what people look to consume, in order, is roughly:
code samples
HOWTO
FAQ
user guide
reference manual
It is very likely that 1) will get copy-pasted and the reader will move on. The most important artifact on that list is 5) however it will be read by very few. Many communities I interact with today prioritize on popularity with 5) being nearly non-existent. I find this impossible because I would only use the previous steps as hints, guiding me to the definitive information in 5). I am lost when there are no clear rules defined.
The Erlang community has used the traditional engineering approach, prioritizing specification over prose. The gen_statem documentation is an example of that, I like that it is very well specified but even I find it hard to read.
I definitely recognize myself from a few months ago for some problems, and I still do not know the answer for some others…
Also, as you rightfully outlined, I am strongly biased towards releases etc…
My thesis forced me to look into them pretty early on.
To give an idea of how early, I had no prior experience in Erlang apart from a short project done for a distributed programming class.
I have to agree that, at first, I found Erlang’s documentation quite overwhelming. However, after getting used to it, I tend to appreciate the the precision and the amount of details that is included in it. I think that what I like is that no guess work is involved when coding.
This being said, I agree that some module’s documentation is hard to comprehend without any example. I think that Elixir’s documentation, in this regard, does a better job.
Jumping on the documenation train. My personal pet peeve is the eunit documentation. I only mostly understand it because I’ve used a lot of other unit test frameworks. It seems like it was written with a computation theory crowd in mind.
… while not stopping the node it was attached to I don’t know how many times I called q(). on a live node out of habit, instantly followed by calling “Oh, damn ”
There is no unified documentation/manual consensus on building simple applications. Lets say i want to build a trivial web server:
After i learned Erlang from multiple books i have to :
search and read about rebar ( config , profiles etc - this thing here took me weeks to get right)
then have to search and read about Cowboy/Nova
then lets say i made some endpoints , i have to search for some library for doing a thing as basic as serializing , (e.g thoas) have to search for it , have to see how it works…its just incredible that i have to put this much effort in something so trivial as serialization
There is just no 1 go -to place that binds them all. I feel the worst part is the scattered brain symptom that i get anytime i want to put an application together.
And now god forbid , lets say i want to run my app in docker / kubernetes , i have to look on forums to understand some weird setting in rebar or whatever…
I feel the worst part of Erlang is the lack of organization of the resources available on the internet.
Nova project does that good , it integrates alot of dependencies and everyday libraries , but aside from that it just feels like the ecosystem (documentation-wise) is behind others by a lot.
Alot of times i see very long lists of tuples on how to configure Rebar for example or some other library. I don’t really care about that when i am starting , i just want to get my app running, and then have links to understand more in depth specific parts of the config
As someone who’s been using Erlang/OTP for more than ten years, I can honestly say that I’ve never bothered to figure out appups and relups.
I don’t know whether that puts them firmly out of “things a beginner should know” or firmly into “beginners should know this, but it’s insanely difficult”…
I have done plenty of hot-code-reloads in production, usually after a deploy, when we’ve spotted a minor bug but we didn’t want to go through the rigmarole of another full deploy (because of reasons, they were multi-hour semi-manual efforts, so we only did them once a month or so).
.
I don’t know how many times I called 
”