I agree about the content of Elixir's docs. They seem to have inherited the habit of documenting things well, which is a fuckin great habit to have.
But. Honestly, I hate the hell out of how Elixir's docs look, and am pretty unhappy with how Erlang's docs started aping the style.
Seriously, check out the EBNF-esque description of the types for this function: <https://web.archive.org/web/20170509122932/http://erlang.org...>. Notice also how some of the documentation for all of the 'request' variants fits on a single screen. Scroll to the top of the page and notice the regular formatting and prominent, clear section headings. See how the significant data types used by the module are described in one place. Scroll to the bottom and observe the "See also" section. Notice the very clear navigation on the left-hand side that gives you obvious springboards to any part of the documentation.
Compare that to this: <https://www.erlang.org/doc/apps/inets/httpc.html#request/1>. Notice how you get a function or three of typespec on a screen. There's so much scrolling to get to the function's behavioral description. And the EBNF has been replaced with raw typespecs! If you understand how to read Erlang typespecs, it's totally possible to read the function type. But, like, if you're starting out with the language, this is WAY harder to read. Not to mention the loss of the clear headings at the top of the document and the centralized list of data types, as well as the "phone style" navigation widget on the left that obscures at least as much as it reveals.
But. Honestly, I hate the hell out of how Elixir's docs look, and am pretty unhappy with how Erlang's docs started aping the style.
Seriously, check out the EBNF-esque description of the types for this function: <https://web.archive.org/web/20170509122932/http://erlang.org...>. Notice also how some of the documentation for all of the 'request' variants fits on a single screen. Scroll to the top of the page and notice the regular formatting and prominent, clear section headings. See how the significant data types used by the module are described in one place. Scroll to the bottom and observe the "See also" section. Notice the very clear navigation on the left-hand side that gives you obvious springboards to any part of the documentation.
Compare that to this: <https://www.erlang.org/doc/apps/inets/httpc.html#request/1>. Notice how you get a function or three of typespec on a screen. There's so much scrolling to get to the function's behavioral description. And the EBNF has been replaced with raw typespecs! If you understand how to read Erlang typespecs, it's totally possible to read the function type. But, like, if you're starting out with the language, this is WAY harder to read. Not to mention the loss of the clear headings at the top of the document and the centralized list of data types, as well as the "phone style" navigation widget on the left that obscures at least as much as it reveals.