5 ms·

From the perspective of someone coming the other direction (a developer working almost entirely with Elixir that needed to jump to Erlang docs occasionally), it

From the perspective of someone coming the other direction (a developer working almost entirely with Elixir that needed to jump to Erlang docs occasionally), it's interesting to see the note on docs, and honestly the vibe I get from this blog post feels related to my personal overall gripe with the Erlang community. To be blunt, I really dreaded needing to jump to the Erlang documentation, largely because of a perceived gap in developer empathy. Elixir documentation feels like it's written in a way that wants you to be successful and enjoy the process, while Erlang documentation feels very perfunctory. Where Elixir documentation is rife with examples and hints, Erlang documentation almost makes you feel like an idiot for wanting to see similar examples. I wonder how much of that vibe is more due to priming because of community perception more than anything else. There's a distinct stereotype of Erlangers having a strong "I am very smart" vibe. That's not fair to a lot of the wonderful Erlang fans I've met that are extremely welcoming, but the wider Erlang community has a strong perception of gatekeeping where they almost don't seem like they want the language to be more accessible.

eterm 6y ago
It's like 2000's MSDN vs current MSDN. The erlang documentation tells you what you need to know and is accurate but it isn't helpful in the way it should be. If you already know what you're doing, it can be a useful reference, but it doesn't aid understanding.
- enraged_camel 6y ago
  In other words, it's a spec sheet, which is useful for people who are already experts in the language. Beginners and intermediates, on the other hand, need it to be something more like a textbook: something that contain not just the technical details, but also commentary and examples about them that tie them to "real life" scenarios.
- heleninboodler 6y ago
  > 2000's MSDN vs current MSDN Which one is better? I've been out of that world for close to 15 years.
dnautics 6y ago
I onboarded a python dev onto elixir and he complained that elixir docs don't look like python docs, so it must be to some degree a matter of taste. I gotta say I don't hate the official erlang docs, they're not terrible. The state of documentation in erlang libraries, though, is frankly atrocious. Even libraries that had their genesis in elixir (like telemetry) are basically unbearable to read. I wish at least there were a reasonable way to get erlang libraries to have their docs laid out exactly like the erlang docs.
- nickjj 6y ago
  > I onboarded a python dev onto elixir and he complained that elixir docs don't look like python docs, so it must be to some degree a matter of taste. As someone who also came from Python I can't say I'm a fan of Elixir's docs either. I often find myself having to externally search for Elixir / Phoenix resources and when you compare Python vs Elixir in that regard it's no contest. Almost every web dev problem you could think of is solved in Python with tons of examples, practical applications, blog posts, YouTube videos and the raw docs themselves. You'll almost certainly find high quality code you can at least work off of. Where as with Elixir I find myself hitting dead ends in a lot of places and the docs often don't have enough details or context to understand something unless you're already an expert in which case you wouldn't need the docs. There's often 1 liners that expect you to have an understanding of the language that rivals its creator. At the end of the day it's not really about the literal documentation. It's how fast you can go from being stuck to unstuck and walking away with understanding how you got from stuck to unstuck.
  - mmcclure 6y ago
    I'd argue you're not commenting on any specific language at all here, but rather the sheer size of the community/user base for a given language.
    - nickjj 6y ago
      > I'd argue you're not commenting on any specific language at all here, but rather the sheer size of the community/user base for a given language. Yes and no. A larger community will for sure help with filling in knowledge gaps, but those gaps stem from the documentation not covering something in enough detail. Maybe it's just me but whenever I read Elixir, Phoenix or Ecto's docs I can't really relate to them. It feels like they are written for a completely different type of person and very rarely do they focus on practical applications of something. Most of the docs feel more like a reference guide to a library's API and if you're lucky you'll get an example or 2, but there's not enough context written around it to figure out how to apply that to your specific problem. That and the docs are rarely linked to a meaningful result when Googling for stuff. It's a much different world than Python, Ruby and PHP IMO.
crad 6y ago
I could see that, my biggest gripe with Erlang has always been around the "softer edges" - easy to grok tooling, easy to read documentation, etc. And something to work on for sure.
- dnautics 6y ago
  A lot of these things are made more difficult due to lexical substitution as it's metaprogramming primitive.
hinkley 6y ago
I've found that in general the longer someone has been on a project, the worse their documentation is. People who have both deep practical knowledge of a domain and can explain it clearly are so rare that we tend to remember them by name. Experts can bitch all they want about how Neil deGrasse Tyson isn't a 'real astrophysicist', but lets see you try to talk to the general public, or for that matter, college students starting their senior year as undergrads in your field. Then lets have them frankly rate you on your lack of accessibility, tendency to circular reasoning, overuse of jargon, and complete lack of patience... We'll call it the head-up-own-ass quotient. Erlang is a very, very old project, with a historically high degree of echo chamber going on. Without active pushback from a dedicated member of the core team, such things usually end in utter chaos. It is less likely that you will achieve understanding by reading documentation of that sort, than that you will accidentally summon an eldritch horror by reading it aloud and not being very precise with your pronunciation.
- jacquesm 6y ago
  > Without active pushback from a dedicated member of the core team, such things usually end in utter chaos. That may well be true, but Erlang is actually the opposite of utter chaos, it is extremely well designed, organized and implemented and battle hardened to a degree that would put most FOSS projects to shame.
  - whelming_wave 6y ago
    My reading was that they were saying the documentation would end in utter chaos, not the project as a whole.
    - jacquesm 6y ago
      Erlangs documentation is fine. It's not 'modern', but it is actually quite good. There is a lot of it though and it isn't newbie friendly, which is a niche filled by some excellent books out there, for instance the (free!) Learn You Some Erlang website/book: https://learnyousomeerlang.com/ https://learnyousomeerlang.com/
nobleach 6y ago
This is my experience with OCaml docs too. Basically just type signatures/function signatures. I typically use Elixir's docs as one of my go-tos for a "Gold Standard". I mentioned this in the ReasonML community too. Whatever you do, do NOT adopt the OCaml way. Their API docs seem to be getting better.

eterm 6y ago

It's like 2000's MSDN vs current MSDN. The erlang documentation tells you what you need to know and is accurate but it isn't helpful in the way it should be. If you already know what you're doing, it can be a useful reference, but it doesn't aid understanding.

enraged_camel 6y ago
In other words, it's a spec sheet, which is useful for people who are already experts in the language. Beginners and intermediates, on the other hand, need it to be something more like a textbook: something that contain not just the technical details, but also commentary and examples about them that tie them to "real life" scenarios.
heleninboodler 6y ago
> 2000's MSDN vs current MSDN Which one is better? I've been out of that world for close to 15 years.

dnautics 6y ago

I onboarded a python dev onto elixir and he complained that elixir docs don't look like python docs, so it must be to some degree a matter of taste. I gotta say I don't hate the official erlang docs, they're not terrible. The state of documentation in erlang libraries, though, is frankly atrocious. Even libraries that had their genesis in elixir (like telemetry) are basically unbearable to read. I wish at least there were a reasonable way to get erlang libraries to have their docs laid out exactly like the erlang docs.

nickjj 6y ago
> I onboarded a python dev onto elixir and he complained that elixir docs don't look like python docs, so it must be to some degree a matter of taste. As someone who also came from Python I can't say I'm a fan of Elixir's docs either. I often find myself having to externally search for Elixir / Phoenix resources and when you compare Python vs Elixir in that regard it's no contest. Almost every web dev problem you could think of is solved in Python with tons of examples, practical applications, blog posts, YouTube videos and the raw docs themselves. You'll almost certainly find high quality code you can at least work off of. Where as with Elixir I find myself hitting dead ends in a lot of places and the docs often don't have enough details or context to understand something unless you're already an expert in which case you wouldn't need the docs. There's often 1 liners that expect you to have an understanding of the language that rivals its creator. At the end of the day it's not really about the literal documentation. It's how fast you can go from being stuck to unstuck and walking away with understanding how you got from stuck to unstuck.
- mmcclure 6y ago
  I'd argue you're not commenting on any specific language at all here, but rather the sheer size of the community/user base for a given language.
  - nickjj 6y ago
    > I'd argue you're not commenting on any specific language at all here, but rather the sheer size of the community/user base for a given language. Yes and no. A larger community will for sure help with filling in knowledge gaps, but those gaps stem from the documentation not covering something in enough detail. Maybe it's just me but whenever I read Elixir, Phoenix or Ecto's docs I can't really relate to them. It feels like they are written for a completely different type of person and very rarely do they focus on practical applications of something. Most of the docs feel more like a reference guide to a library's API and if you're lucky you'll get an example or 2, but there's not enough context written around it to figure out how to apply that to your specific problem. That and the docs are rarely linked to a meaningful result when Googling for stuff. It's a much different world than Python, Ruby and PHP IMO.

crad 6y ago

I could see that, my biggest gripe with Erlang has always been around the "softer edges" - easy to grok tooling, easy to read documentation, etc. And something to work on for sure.

dnautics 6y ago
A lot of these things are made more difficult due to lexical substitution as it's metaprogramming primitive.

hinkley 6y ago

I've found that in general the longer someone has been on a project, the worse their documentation is. People who have both deep practical knowledge of a domain and can explain it clearly are so rare that we tend to remember them by name. Experts can bitch all they want about how Neil deGrasse Tyson isn't a 'real astrophysicist', but lets see you try to talk to the general public, or for that matter, college students starting their senior year as undergrads in your field. Then lets have them frankly rate you on your lack of accessibility, tendency to circular reasoning, overuse of jargon, and complete lack of patience... We'll call it the head-up-own-ass quotient. Erlang is a very, very old project, with a historically high degree of echo chamber going on. Without active pushback from a dedicated member of the core team, such things usually end in utter chaos. It is less likely that you will achieve understanding by reading documentation of that sort, than that you will accidentally summon an eldritch horror by reading it aloud and not being very precise with your pronunciation.

jacquesm 6y ago
> Without active pushback from a dedicated member of the core team, such things usually end in utter chaos. That may well be true, but Erlang is actually the opposite of utter chaos, it is extremely well designed, organized and implemented and battle hardened to a degree that would put most FOSS projects to shame.
- whelming_wave 6y ago
  My reading was that they were saying the documentation would end in utter chaos, not the project as a whole.
  - jacquesm 6y ago
    Erlangs documentation is fine. It's not 'modern', but it is actually quite good. There is a lot of it though and it isn't newbie friendly, which is a niche filled by some excellent books out there, for instance the (free!) Learn You Some Erlang website/book: https://learnyousomeerlang.com/ https://learnyousomeerlang.com/

nobleach 6y ago

This is my experience with OCaml docs too. Basically just type signatures/function signatures. I typically use Elixir's docs as one of my go-tos for a "Gold Standard". I mentioned this in the ReasonML community too. Whatever you do, do NOT adopt the OCaml way. Their API docs seem to be getting better.