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

[Vlad Dumitrescu]

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 don't know what Kenneth wanted to highlight with the Elixir docs, but I
don't think that he meant the exact presentation.
What I looked at is the different structure and what things are emphasized.
The details are easy to fix (font sizes, colors, placement, etc)
if the underlying HTML is friendly to it (i.e. not everything is a <p>, but
there are selectors for "summary", "examples", "specs", etc).

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.

IMHO, presenting reference documentation so that everybody is pleased is
extremely difficult, because people use the docs in many different ways.
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)
than for people that mostly know what they look for (that need fast access
to some detail, often from the shell).

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
huge and needs to be folded. I can't come up with a way to do that without
javascript.

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 :-)
https://www.dropbox.com/s/jqpqpcimv3qxdce/e0.png?dl=0

regards,
Vlad



> 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/fe98872c/attachment.htm>