Elixir Docs are Built Different

A few common refrains from developers who are new to Elixir are:

• “Where are the blog posts?”
• “Stack Overflow?”
• “Google was no help…”

And I totally get it, if you come from another language ecosystem, you would be right to prioritize tutorials or blog posts first. It is just way more likely you get a useful snippet than if you read the official docs, if you can find them at all.

In Elixir that is simply not the case, our documentation is not only fairly easy to navigate, it also includes copious amounts of discussion, guides and examples in the docs for a Module.

Map

Lets dive right in to an example. Say we are going to use a Map data structure in Elixir. If we go to the official documentation for Map we will find almost two whole pages of discussion on what a map is, how to use it, warnings on its usage and with extensive examples. Further, if we search on Google “elixir map” this page will be the top result.

If we continue scrolling, you will find any type information that’s defined. Then a list of every function defined in that module, with examples and type specs for each! Crucially, each example also shows what the expected output would be. These are also called Doctests and executed as tests. Take a step back and appreciate that for a second, you know these examples work because it would break the build if they didn’t! Further, you can write Doctests in your own code and execute them as tests as well!

If we click the little </> icon next to its name (at the top right of the above screenshot) we get brought to the definition in GitHub!

Because Elixir is an immutable and functional language, what you see is what you get. Nine times out of ten, if the documentation sucks, we can simply read the code to get a better idea of what’s going on. I should mention, if we’re using a library that has a ton of macros, this will get harder to navigate. And this isn’t just Elixir the language that is like this, every library on hex.pm has auto-generated documentation hosted on hexdocs.

Hex

Hex is another valuable resource for Elixir developers, below is an annotated screenshot from one of my favorite libraries, jason.

A. Takes you to the online hosted docs. Usually hexdocs, but developers can host it or configure it however they want. B. Links to that version’s documentation. C. Links to the code diff between that version and the previous one. More on this in a second. D. Lists every package that depends on this library, in order of downloads. This can be a good indicator that it is a solid package.

In this one page, we have access to everything about this library and the ability even review the code before we upgrade. Here is the diff between version 1.3.0 and 1.4.0 for jason.

This is incredible, with a single click we can review a package, and its changes entirely in one page. If you direct your attention to the URL you will see 1.3.0..1.40 we can change those to see the diff between any version. So if we skipped a few versions, we can review it before accepting the change blindly!

Wrapping up

A big part of learning any new language is learning how to “read the manual”. In the case of Elixir, developer documentation has always been a top priority, with an ongoing effort to improve it. I am going to list off a couple of the “Greatest Hits” when it comes to documentation, and I hope you enjoy!

• Ecto: these docs are the most used page for me in all of hexdocs, partially because it is a huge library that does a ton, but also because It’s just so full of useful knowledge.
• Phoenix Guides: these tutorials are actually written in the Phoenix repository right alongside the code.
• NimbleParsec: this is a library for generating fast text-based parser combinators, if you don’t know what that is simply read the doc! I had no idea what they were before I read these docs, and they turn out to be incredibly helpful!