<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Sep 28, 2016 at 3:58 AM, Richard A. O'Keefe <span dir="ltr"><<a href="mailto:ok@cs.otago.ac.nz" target="_blank">ok@cs.otago.ac.nz</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span><br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Have you looked at the Elixir doc for<br>
example <a href="http://elixir-lang.org/docs/stable/elixir/Kernel.html" rel="noreferrer" target="_blank">http://elixir-lang.org/docs/st<wbr>able/elixir/Kernel.html</a>?<br>
</blockquote>
<br></span>
I have.<br>
I see EXTREMELY wide margins in the main panel.<br>
This is a waste of my screen real estate and gives me<br>
a bad feeling straight away.</blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I see SMALL characters in the main panel.<br></blockquote><div><br></div><div>I don't know what Kenneth wanted to highlight with the Elixir docs, but I don't think that he meant the exact presentation. </div><div>What I looked at is the different structure and what things are emphasized. The details are easy to fix (font sizes, colors, placement, etc) </div><div>if the underlying HTML is friendly to it (i.e. not everything is a <p>, but there are selectors for "summary", "examples", "specs", etc). </div><div><br></div><div>I can only see one major difference: the function list for a module is inline (elixir) instead of in the sidebar (erlang). Which one is best? I've heard people arguing for both.</div><div><br></div><div>IMHO, presenting reference documentation so that everybody is pleased is extremely difficult, because people use the docs in many different ways.<br></div><div>Different layout and information detail are most useful for beginners (that browse to see what's available and might learn something unrelated in the process) </div><div>than for people that mostly know what they look for (that need fast access to some detail, often from the shell). </div><div><br></div><div>It's also difficult to create a presentation that works for a full-blown browser as well as for lynx. I'm not referring to the visuals, but the module and function index, which is </div><div>huge and needs to be folded. I can't come up with a way to do that without javascript. </div><div><br></div><div>BTW, it's trivial (see comment above regarding html friendliness, though) to make the erlang docs look more like elixir's while keeping the good parts. See picture :-)</div><div><a href="https://www.dropbox.com/s/jqpqpcimv3qxdce/e0.png?dl=0">https://www.dropbox.com/s/jqpqpcimv3qxdce/e0.png?dl=0</a><br></div><div><br></div><div>regards,</div><div>Vlad</div><div><br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I've actually told my browser never to show characters<br>
as smaller than 14pt, but somehow the Elixir page is<br>
overriding that.<br>
<br>
By the way, this already raises a MAJOR accessibility<br>
issue.  Tim Berners-Lee always wanted HTML to be usable<br>
by people who had poor vision or none.  One of the points<br>
of using Cascading Style Sheets is that the user is<br>
supposed to be able to set defaults (like no small text)<br>
that the web page cannot (or at least should not) override.<br>
That means that setting font sizes is a VERY user-hostile<br>
thing for a web designer to do, and means that you have<br>
(or at least should exert) much less control over layout<br>
than you think.<br>
<br>
There is something worse.  The code examples on the page<br>
are in an even SMALLER font than the text, and they are<br>
in pale colours (pale orange, pale purple) against a white<br>
background, making them even HARDER to see.<br>
<br>
In the summary, the text is in italics for no apparent<br>
reason.  On the evidence so far, I can only assume that the<br>
reason is to make it harder to read.<br>
<br>
So just at first glance I can tell that the author hates me.<br>
<br>
And this you think is "quite good"?<br>
<br>
I see a dark blue? grey? purple navbar.  The text is even<br>
SMALLER than the code text in the main panel, and appears to<br>
be pale blue against dark blue.  It's a strain to read.<br>
It's a list of modules.  The fact that it is possible to<br>
get a list of functions is far from obvious.  (I expected<br>
it to be a link.)<br>
<br>
It doesn't help that I find dark colours depressing and my<br>
eyes automatically turn away from big dark blobs, so it<br>
takes conscious effort to attend to the navbar.  It's just<br>
so dark and ugly.<br>
<br>
Not content with wasting about half of the horizontal extent<br>
of the main panel, when I go to the "Functions" part of the<br>
page, it wastes about half of the vertical extent of the<br>
main panel with unnecessary white space.  It wastes much of<br>
the rest with trivial examples.  I love examples, but I do<br>
not want to see them ALL the time.<br>
<br>
And this you think is "quite good"?<br>
<br>
While I'm no spring moa, I have new glasses and am accepted<br>
as fine for driving, and am comfortable reading printed<br>
10-point type.  (Why then do I set 14pt minimum in the browser?<br>
High resolution screen, and designers who count pixels instead<br>
of points.  Web designers tend to assume that their resolution<br>
is everyone's resolution.  I remember being slammed as a moron<br>
by one web designer for not knowing that screen resolutions<br>
higher than 72 dots per inch didn't exist, at a time when I was<br>
using a Mac with 90 dots per inch.)<br>
<br>
I am prepared to swear in court that man pages are much<br>
easier for me to read than this web page.<br>
<br>
It is clear that a huge amount of work has gone into the<br>
Elixir web pages, trying to make them visually attractive.<br>
(Abuse of the principle of mediocrity:  If I like it,<br>
everyone likes it.)  And it's also clear that a lot of<br>
effort has gone into providing examples.<br>
<br>
It's just that for me the Elixir pages are unpleasant<br>
*because* of the work that has gone into them.<br>
<br>
It seems pretty obvious that HTML pages that *I* think<br>
are beautiful will look horrible to someone else.<span><br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I think the layout and function is quite good and the handling of css<br>
and javascript is from what I can understand<br>
handled nicely.<br>
</blockquote>
<br></span>
I can't think of any good reason for Erlang documentation pages<br>
to contain any JavaScript whatsoever.  Lynx doesn't include a<br>
JavaScript interpreter, and Emacs-W3 doesn't include a JavaScript<br>
interpreter, and for that matter, one of the web browsers I use<br>
from time to time doesn't include a JavaScript interpreter.<br>
(No, navbars *don't* need JavaScript.)<br>
<br>
For search, I'd like to use a proper IR engine.  You *really*<br>
don't want to load an IR index into every page.<div><div><br>
______________________________<wbr>_________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org" target="_blank">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/list<wbr>info/erlang-questions</a><br>
</div></div></blockquote></div><br></div></div>