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

Anthony Ramine <>
Wed Sep 28 11:22:52 CEST 2016


Replied inline.

> Le 28 sept. 2016 à 03:58, Richard A. O'Keefe <> a écrit :
> 
> 
> 
>> 
>> 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.

So why do you hardwrap all your emails by hand to 50 columns? You are wasting my real screen estate. Do you hate me? :(

How can a website not waste horizontal real estate in huge windows without ending up unreadable because of very long lines of text?

This is what your email looks to me btw: https://goo.gl/HLSJ5G

> 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.

At least you can read the text and see the colours. The Erlang documentation uses iframes and doesn't have navigation links, making it quite useless to screen readers. The colour issues are easily fixable and I think José is happy to get feedback about them. The Erlang documentation accessibility issues are far worse.

> 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"?

Would you prefer 200 characters lines? Because that's not readable by any standard.

> 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.)

It has been years since CSS pixels' stopped corresponding to device pixels though.

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

Most of the text on that webpage is 12pt. Is the size a problem for you, or just the constract issues you mentioned earlier?

> 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.

Would tailoring to your specific needs be abuse of mediocrity?

>> 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.)

Syntax colouring of examples usually need JS because otherwise the HTML markup to be downloaded becomes really heavy.

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

Why not? Indices can be long-time-cached JS assets and then searches are very quick and convenient. Cf. searches on https://doc.rust-lang.org/std/vec/struct.Vec.html for example.

Regards.



More information about the erlang-questions mailing list