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