Hacker News Reader

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.

> 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.

My reading was that they were saying the documentation would end in utter chaos, not the project as a whole.

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/

I find it frustrating how often on Hackernews people jump into the middle of a conversation as if the beginning of the conversation never happened.

From the top level comment:

> To be blunt, I really dreaded needing to jump to the Erlang documentation,

> 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.

You mean like Feynman, Hawking, Penrose, Brian Green, Richard Dawkins, Steven Pinker, Freeman Dyson, Edward Frenkel and so on?

I agree that it is not a sin to be "just" a science popularizer _a la_ Asimov and people who hold that belief are just being obtuse. Equally obtuse are the people who think "Those scientists cannot communicate with the common man", well guess what, that skill is distributed almost randomly among that lot, so for every scientist with an opaque style there is a wonderful communicator. The same happen in IT/CS and in any other field.

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.

> 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.

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.

> 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.

> 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.

My only experience before Phoenix was Django, and I have to say, even though it took a little while to wrap my head around Phoenix, it was about the same time it took to get my head around Django. Once I did, I found Pheonix to be more expressive and exceedingly productive.

Elixir's docs and guides are quite thorough and overwhelmingly focused on practical applications, I'm sorry that you clearly haven't had a good experience personally.

Again, though, reading between the lines, it sounds distinctly like your complaint is with the ecosystem and its maturity, not anything to do with the language itself. "No, it's not that!" you say, as you go on to mention three very, very mature languages with massive ecosystems that I do agree are a very different world.

Python, Ruby, and PHP are all great! It's difficult to even think of a language that has a better wealth of guides and resources out there than any of those three (with the exception of maybe JavaScript). Elixir and Erlang, two fairly niche languages that are the actual topic of conversation for this overarching thread, simply aren't comparable in that regard.

When Ruby and Rails were first getting popular in the English-speaking world, around 2008 to 2011, the documentation and community really were excellent for their size, which was a substantial contributing factor to the growth of the language. PHP, on the other hand, was pretty appalling.

Elixir inherited some of the Ruby history and contributors, and has some of the same strengths.

I totally agree with you. I started learning Python about 14-15 years ago before its current popularity and its seemed to have a focus on clarity and ease of getting started. The Elixir docs less so but still ok. Ecto docs was where it started to really annoy me though.

However, after a year of developing and learning elixir I am dropping it. Just did not like it in the end, I prefer other languages and everything I like about Elixir was basically Erlang.

Python community and resources are amazing!

I really don't like Python but I often find loads of code in Python which do exactly what I need, so I prototype things in Python and then port them to whatever language I'm using.

I can't say I've been impressed with Python docs, it's more the surrounding community / blog posts / stack overflow which does it for me.

nick, on several platforms you have done nothing but kvetch about your elixir onboarding experience. I think it's pretty good for most people, but at the same time it's just not for everyone, and I can think only one of two things is going on.

1. You drew the unlucky straw and it's not for you, for whatever reason. 2. You have a closed-minded mentality and it's keeping you from learning elixir.

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.

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.

> 2000's MSDN vs current MSDN

Which one is better? I've been out of that world for close to 15 years.

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.

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.

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