High-level documentation?

First of all, I love that Elixir comes with a built-in documentation tool.

However, being a newcomer in Elixir and browsing documentation daily, my experience is that while API documentation is usually comprehensive, high-level “overview/guide/usage” documentation is lacking.

I know that ExDocs supports “extra” files but in practice the community doesn’t seem to use them that much. I wonder if mix generated a docs folder with a couple of empty files such as Overview.md, Usage.md or similar, it would nudge people towards filling them in.

A useful template/guide is at Write the Docs, and hosting is available (similar to hexdocs) in Read the Docs

Let me know if this discussion warrants an issue!


I believe this is a useful suggestion but makes me wonder if ExDoc should be a dependency for newly generated projects - and then we need to discuss the consequences of this change.

On the other hand, now that Phoenix is migrating to ExDoc for their own guides, I wonder if it will push for more usage of such ExDoc features, because I believe the biggest problem right now is that most don’t know it exists.

1 Like

For many libraries and stdlib modules, I feel like the moduledoc is frequently treated like such “overview” with a more narrative way of introducing things. They frequently feature some high-level examples of composing multiple functions and how they interact with other parts of the system.


Have you given any thought to including externally-facing API documentation as part of exdoc?

I’m thinking specifically of HTTP and socket APIs.

The generated module documentation for controllers and channel handlers is IMHO not particularly useful (surprise, surprise, my module has a handle_in callback!), but a list of the channel messages it accepts or sends along with some documentation on how to use those would be very handy.


This discussion is old I have seen it just now but ExDoc does support custom guides. Phoenix is using it from version v1.3 to power their own guides.