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

[José Valim]

> I've actually told my browser never to show characters as smaller than
14pt, but somehow the Elixir page is overriding that.

I could not reproduce this on Safari, Chrome and Firefox. I would
appreciate if you could send me your browser and respective version,
possibly in private to not derail the discussion, so I can file a proper
bug report. We have actually put a good amount of effort to ensure the page
scales up and down accordingly when using the browser zoom features,
including mobile and other devices.

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

Good point. I will also open up an issue to discuss the use of italics.

> The fact that it is possible to get a list of functions is far from
obvious.  (I expected it to be a link.)

Yup, as mentioned in previous replies, this is already on the bug reports
list.


*José Valim*
www.plataformatec.com.br
Skype: jv.ptec
Founder and Director of R&D

On Wed, Sep 28, 2016 at 3:58 AM, Richard A. O'Keefe <ok@REDACTED>
wrote:

>
>
>
>> 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.
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160928/f7abca90/attachment.htm>