Elixir Docs are Built Different

Illustration of a road leading to mountains.
Image by Annie Ruygt

We’re Fly.io. We run apps for our users on hardware we host around the world. Fly.io happens to be a great place to run Phoenix applications. Check out how to get started!

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.


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.

Flowchart showing how a LiveView process works.

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!

Flowchart showing how a LiveView process works.

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!

Flowchart showing how a LiveView process works.

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 is another valuable resource for Elixir developers, below is an annotated screenshot from one of my favorite libraries, jason.

Flowchart showing how a LiveView process works.

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.

Flowchart showing how a LiveView process works.

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!

Fly.io ❤️ Elixir

Fly.io is a great way to run your Phoenix LiveView app close to your users. It’s really easy to get started. You can be running in minutes.

Deploy a Phoenix app today!