[erlang-questions] Erlang documentation -- a modest proposal
Tue Sep 27 14:06:30 CEST 2016
On 09/27/2016 01:13 PM, Kenneth Lundin wrote:
> On Tue, Sep 27, 2016 at 11:46 AM, Joe Armstrong <
> <mailto:>> 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
> 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,
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
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
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
(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.)
Author of The Erlanger Playbook,
A book about software development using Erlang
More information about the erlang-questions