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

[Richard A. O'Keefe]

>
> Have you looked at the Elixir doc for
> example http://elixir-lang.org/docs/stable/elixir/Kernel.html?

I have.
I see EXTREMELY wide margins in the main panel.
This is a waste of my screen real estate and gives me
a bad feeling straight away.
I see SMALL characters in the main panel.
I've actually told my browser never to show characters
as smaller than 14pt, but somehow the Elixir page is
overriding that.

By the way, this already raises a MAJOR accessibility
issue.  Tim Berners-Lee always wanted HTML to be usable
by people who had poor vision or none.  One of the points
of using Cascading Style Sheets is that the user is
supposed to be able to set defaults (like no small text)
that the web page cannot (or at least should not) override.
That means that setting font sizes is a VERY user-hostile
thing for a web designer to do, and means that you have
(or at least should exert) much less control over layout
than you think.

There is something worse.  The code examples on the page
are in an even SMALLER font than the text, and they are
in pale colours (pale orange, pale purple) against a white
background, making them even HARDER to see.

In the summary, the text is in italics for no apparent
reason.  On the evidence so far, I can only assume that the
reason is to make it harder to read.

So just at first glance I can tell that the author hates me.

And this you think is "quite good"?

I see a dark blue? grey? purple navbar.  The text is even
SMALLER than the code text in the main panel, and appears to
be pale blue against dark blue.  It's a strain to read.
It's a list of modules.  The fact that it is possible to
get a list of functions is far from obvious.  (I expected
it to be a link.)

It doesn't help that I find dark colours depressing and my
eyes automatically turn away from big dark blobs, so it
takes conscious effort to attend to the navbar.  It's just
so dark and ugly.

Not content with wasting about half of the horizontal extent
of the main panel, when I go to the "Functions" part of the
page, it wastes about half of the vertical extent of the
main panel with unnecessary white space.  It wastes much of
the rest with trivial examples.  I love examples, but I do
not want to see them ALL the time.

And this you think is "quite good"?

While I'm no spring moa, I have new glasses and am accepted
as fine for driving, and am comfortable reading printed
10-point type.  (Why then do I set 14pt minimum in the browser?
High resolution screen, and designers who count pixels instead
of points.  Web designers tend to assume that their resolution
is everyone's resolution.  I remember being slammed as a moron
by one web designer for not knowing that screen resolutions
higher than 72 dots per inch didn't exist, at a time when I was
using a Mac with 90 dots per inch.)

I am prepared to swear in court that man pages are much
easier for me to read than this web page.

It is clear that a huge amount of work has gone into the
Elixir web pages, trying to make them visually attractive.
(Abuse of the principle of mediocrity:  If I like it,
everyone likes it.)  And it's also clear that a lot of
effort has gone into providing examples.

It's just that for me the Elixir pages are unpleasant
*because* of the work that has gone into them.

It seems pretty obvious that HTML pages that *I* think
are beautiful will look horrible to someone else.

> I think the layout and function is quite good and the handling of css
> and javascript is from what I can understand
> handled nicely.

I can't think of any good reason for Erlang documentation pages
to contain any JavaScript whatsoever.  Lynx doesn't include a
JavaScript interpreter, and Emacs-W3 doesn't include a JavaScript
interpreter, and for that matter, one of the web browsers I use
from time to time doesn't include a JavaScript interpreter.
(No, navbars *don't* need JavaScript.)

For search, I'd like to use a proper IR engine.  You *really*
don't want to load an IR index into every page.