# Title to be defined

ExDoc has a cool new feature, [Cheatsheets](https://hexdocs.pm/ex_doc/cheatsheet.html)!

In this blog post, we'll explain what that new feature is and the motivation behind it. We'll also take the opportunity to highlight other ExDoc features that are examples of how it has been evolving to make the documentation experience in Elixir better and better.

## What is ExDoc Cheatsheet and how it improves documentation experience
ExDoc's Cheatsheets are Markdown files with the `.cheatmd` extension. One can use it to write cheatsheets about their Elixir project.

Writing and reading cheatsheets is not exactly a new thing for developers. But, what that feature brings as a novelty is the possibility of integrating a cheatsheet right along with the rest of the documentation of an Elixir project instead of hosting it in a different place.

Developers need different kinds of docs at different times. When one is learning about a new library, a guide format is proper. An API reference can be helpful when one needs to know if that library can solve a specific problem. A cheatsheet could be more practical when someone wants to remember a couple of functions they already used from that library.

Imagine if you'd need to go to a different place for every type of documentation you're looking for. That would make a very fragmented experience. And not only for readers of documentation but also for writers.

What ExDoc Cheatsheet represents is it's one step further in the direction of making documentation in Elixir an even more comprehensive and integrated experience.

It's also worth mentioning that ExDoc Cheatshees is heavily inspired by [devhints.io](https://devhints.io) from [Rico Sta. Cruz](https://twitter.com/rstacruz). And that it was a [community contribution](https://github.com/elixir-lang/ex_doc/pull/1618) from [Paulo Valim](https://twitter.com/paulovalim).

## 10 features that show how ExDoc has improved documentation experience over time
We added Cheatsheets to ExDoc because we value developer experience and believe documentation is a core aspect of it.

Since the beginning, one of Elixir's principles is that documentation should be a first-class citizen. What this idea means to us is that documentation should be easy to write and easy to read. ExDoc has been continuously evolving over the years, guided by that idea.

We thought the release of Cheatsheets could be an excellent opportunity to remember how ExDoc has evolved. Here are some of the features added to ExDoc over the years that make reading and writing documentation in Elixir a great experience.

### Beautiful and usable design
As developers, we may not have the skill to make beautifully designed UIs. That doesn't mean we don't appreciate it.

Here's what ExDoc-based documentation looked like almost ten years ago:


Here's what it looks like today:


The evolution of ExDoc's design made documentation made with it not only more visually appealing but also easier to read and easier to find what you're looking for.

### Links to source code

Sometimes you're reading the docs of a library, and you want to know more about the implementation of a function. Or you found something in the documentation that could be improved and wants to help.

In those situations, it's helpful to go from the documentation to the source code. ExDoc makes that dead easy.

For every module, function, or page, ExDocs gives you a link that you can click to go directly to the project's source code inside Github:


### Guides
One of the most common formats of library or framework documentation is an API reference. But we know that's not the most approachable doc format for when you're just getting started with that lib. Or for when you want to learn how to solve a specific problem using it.

That's why besides API references, ExDoc offers the possibility of writing extra pages. Like Getting Started Guides or How-tos.

Look at how [Ecto's documentation](https://hexdocs.pm/ecto/Ecto.html) uses that, for example:


### Custom grouping of modules, functions, and pages in the sidebar

Sometimes your library has dozens of modules. And sometimes, one given module has a large API surface area. In those situations showing the list of modules or list of functions as a large single list may not be the most digestible way to be consumed.

For those situations, ExDoc allows modules, functions, or even extra pages to be grouped in the sidebar in a way that makes more sense semantically.

Here's an example of how Ecto use grouped functions for its `Repo` module:


Instead of listing `Ecto.Repo` ~40 functions as a single large list, it presents them in different cohesive groups:

- Query API
- Schema API
- Transaction API
- Runtime API
- User callbacks

The same functionality is available for modules and pages (guides, how-tos, etc). Phoenix is a [good example](https://hexdocs.pm/phoenix/overview.html) of that's used.

### Full text search

Sometimes you don't know or don't remember the name of the function that you're looking for. For example, let's say you're looking for a function that's about dealing with file system directories with Elixir.

Although there's no function or module called "directory" in Elixir, when you type "directory" in [Elixir's documentation](https://hexdocs.pm/elixir/search.html?q=directory), it will return all the entries that have the word "directory" inside the documentation. It will even return entries with variations of the word "directory", like "directories", doing a fuzzy search.


The search bar also supports autocompletion for module and function names:


### Keyboard shortcut to navigate to docs of other hex packages

It's usual for an application to have multiple dependencies. And while coding, we usually need to read the documentation of more than one of those dependencies.

One solution is to keep a window open for each package documentation we need. But ExDoc offers another one, a keyboard shortcut to search and go to another package documentation within the same window.

Here's what it looks like:


And there are more keyboard shortcuts to help you navigate within and between documentation:


### A version dropdown to quickly switch to other versions

Keeping our application updated with the latest versions of all its dependencies can be hard. So, it's common to need to look at the documentation of an older version of a library we're using. ExDoc makes it very simple to do that.

When you access the documentation of a project, there's a dropdown that you can use to select the version you're looking for:


### Erlang support

The [EEP 48](https://www.erlang.org/eeps/eep-0048) proposed a standardized way for how BEAM languages could store API documentation. That brought the possibility of any BEAM language to read documentation generated by each other.

By leveraging that work, ExDoc offers the possibility of generating docs for an Erlang project.

Although Elixir developers don't necessarily use Erlang on a daily basis, there are Erlang projects that are common for both languages. For example, Telemetry is a common interface to collect and report metrics for both Elixir and Erlang projects. And the documentation of Telemetry is generated with ExDoc:


That makes it super easy for Elixir developers to read the Telemetry docs because they're already used to ExDoc-based documentation.

### Doctests
- doctests não é um feature do ExDoc. pega alguma coisa?

### Livebook integration
- example: https://twitter.com/mcrumm/status/1585151738482667526