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

[Loïc Hoguin]

On 09/27/2016 01:13 PM, Kenneth Lundin wrote:
> On Tue, Sep 27, 2016 at 11:46 AM, Joe Armstrong <erlang@REDACTED
> <mailto:erlang@REDACTED>> wrote:
>
>     Re: HTML
>
>     I'd very much like to mock up a "nice" HTML display of the functions
>     in a module.
>
>
> Have you looked at the Elixir doc for
> example http://elixir-lang.org/docs/stable/elixir/Kernel.html?
> I think the layout and function is quite good and the handling of css
> and javascript is from what I can understand
> handled nicely.
>
> For an application and modules they present pretty much the same as we
> do today.
> For sure the Elixir community have more cometence around html, css,
> javascript than at least we on the OTP team have.

I have no doubt they are better at HTML, CSS and JS, but they are not 
good at layout and styling IMO.

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.

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.

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

And in case you wonder, it's also unreadable from lynx. This time, 
function names and code examples are indistinguishable.

The list of functions at the top is not very useful overall; 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.

The search result page also gets on top of the documentation you are 
currently reading. Impractical.

The Elixir layout still needs a *lot* of work to be really usable. Not 
to say the Erlang documentation is "the best", but what it needs the 
most is a few tweaks (make it easy to reach every part of the 
documentation from http://erlang.org/doc/) and more content. It's 
already very good, in all its output formats. This would be a huge step 
backward.

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.

(If you worked on the Elixir documentation don't take this personally. I 
have the same amount of criticism over my own, if not more.)

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang