[erlang-questions] Erlang documentation -- a modest proposal

[José Valim]

Thanks Loic, some great feedback in there. Replies inline.


> The lack of indentation alone makes the Elixir documentation unreadable.
> Where do the functions start and end? This is much easier to figure out in
> the Erlang documentation.
>

This has been improved in master:
http://elixir-lang.org/docs/master/elixir/Kernel.html#functions (you may
need a hard reload)


> The huge vertical spacing everywhere makes it so that only about one
> function and a half gets displayed on my screen at a time for equivalent
> amount of information. The Erlang documentation has the double, 3 or 4
> functions.
>

We have a branch where we have reduced the amount of vertical spaces taken
by functions. In some cases though it is more endemic to how the
documentation was written: 4 paragraphs with 1 short-sentence each instead
of 1 paragraph with 4 sentences. Those will take longer to be addressed.


> For some reason all the specs and code examples have a bottom scrollbar
> here even when no scrolling can be done.
>

Those have been fixed in master some time ago. I would definitely recommend
a hard reload (Cmd+R) then.


> The list of functions at the top is not very useful overall


Just as a discussion point: we got a lot of positive feedback from it in
the past. Specially from newcomers that want to have an overview of all
existing functions in a module with a short description. I personally don't
use it.


> the list of functions on the left is better but in the case of Elixir when
> I click "Functions" it scrolls the page for some reason; if I wanted to
> stay where I was and just take a quick look if a function exists, there
> goes my browsing. It also breaks the back/forward buttons for me (bad!).
> Not to mention it's not clear that you can expand it.
>

Agreed. All of those points have already been listed as bugs.


> I also have some concerns with the main Elixir site; the font and font
> size make it hard to read. At least they got the font right in the function
> reference.
>

The font-size has been increased thanks to a PR from Vlad. \o/ If anything
looks suspicious, bug reports are also appreciated.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160928/d06d7e60/attachment.htm>