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

[Richard A. O'Keefe]

On 28/09/16 9:55 PM, Vlad Dumitrescu wrote:
 >>[I was very unhappy about the Elixir Kernel.html page.]

> I don't know what Kenneth wanted to highlight with the Elixir docs, but
> I don't think that he meant the exact presentation.

He certainly praised "layout".

I didn't find the structure especially helpful either.
The distinction between types and functions and macros
is an *IMPLEMENTOR*'s distinction, not a *USER*'s distinction.

Eiffel gets this right:  what is the distinction, *for a user*,
between a named constant, a variable that is exported from a
class (such variables can only be modified by the class's own
code), and a feature (method) with no parameters?  There isn't
any.

What I need is
  - an application or module overview
  - a pointer to separate example modules or scripts (complete things)
    test cases and maybe the source code
  - a list of topics (table-of-contents)
  - within topics
    - an overview of the topic
    - a pointer to examples (code fragments) relating to that topic
      test cases and maybe the source code
    - a list of subtopics (table-of-contents)
    - within subtopics
      - name
      - syntax (type definition, function interface, &c)
      - semantics (what the alternatives for a type mean, what
        is the function supposed to compute)
      - pragmatics (when did it become available, has it been
        superseded and if so by what, are there any performance
        or security issues I should know about)
      - a pointer to examples and test cases and maybe the source code.

The *last* thing I need to know is whether something is a
type, a constant, a function, a macro &c.

In all honestly, organising things by Types Functions Macros
is like the bad old days of Pascal programs where you had to
put all the labels, then all the constants, then all the
types, then all the variables, then all the procedures and
functions, meaning that you had to rip semantically related
things apart on implementation grounds.

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

They are both wrong.  They are alphabetic rather than topical.
This has, for example, the *ABSURD* consequence that
     binary_to_term/1
     term_to_binary/1
are far from each other in the erlang module's documentation.
Similarly, the weeping members of the integer_to_list/1,
list_to_integer/1, float_to_list/1, list_to_float/1 family
are cruelly separated.

More precisely, they are both half right.   If I *know* which
function I want, the alphabetic list helps me find it quickly.
But if I only know what the function is *about*, the alphabetic
list helps very little.

The actual descriptions of semantically related functions should
be physically close in the body of the text so that when I am
looking at one, a related one is just a glance away.

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

If there's anyone here who is NOT a beginner, it's surely Joe
Armstrong.  Yet he has made the point that in each module that
he uses, there is a small number of functions that he uses a lot,
and the rest which he uses very seldom.  That means that
*sometimes* when he looks at dict *sometimes* he will be approaching
it as an expert refreshing his memory about something and
*sometimes* he will be approaching it as a beginning looking for
information about a function he uses so rarely he can't even recall
its name.

Every release there seems to be new stuff in the erlang: module,
so every release I am a beginner again about *something* useful
in that module.

> It's also difficult to create a presentation that works for a full-blown
> browser as well as for lynx.

It doesn't have to be the same HTML file does it?
HTML-optimised-for-Lynx-or-w3m-or-Emacs-w3 and
HTML-optimised-for-Firefox-on-a-huge-screen and
HTML-optimised-for-a-Windows-phone
really need to be three different versions.

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

But I don't *want* "huge" function and module indices
in my pages all the time.  (Hint: "huge" lists are hard
to find things in.)  There's one thing I do heartily
approve of in the Elixir pages, which is that there is a
very simple way to get rid of the navbar.  In fact I'm
personally quite happy to have
  - a module list in one tab
  - a topic (NOT function!) list in another tab
  - the main text scrolled to the current topic in another tab
because quite often when I click on a navbar link what I
want is to see another topic *as well* (in a new tab),
not *instead* of the one I'm looking at.

> 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

Problem 1:  the structure is
  <highly obtrusive bar> <function header>
     Types:
       <argument and result types>

     <text>

   [ Example:
     <Haskell doctest-style example> ]

The word "Types:" is pointless.  I can *see* that they are types.

Problem 2:  if anything should be highlighted here, it is the
function name.  If the function name is bold. there's no need
for the <highly obtrusive bar>, and my eye is directed to the
most salient piece of information.

Problem 3:  the font used for code in the <function header>
and <argument and result types> and the font used for code
in the <text> are not the same font.  Worse still, the
font used for the expression in the <Haskell doctest-style
example> and the font used for the result are not the same
font.  (Or more precisely, they may be different weights of
the same font.)

Problem 4:  the font used for code in the <text> does not have
the same x-height as the font used for ordinary text.  The
code font is markedly smaller.

Problem 5:  the font used for code in the <text> and for the
result in <...example> are markedly fainter than the other
fonts.

I could go on.

But this is the fundamental problem with trying to do fancy
typography in HTML.  It is very very hard to make it look good.
If you want fancy typography that actually looks good,
PDF is the only game in town.

HTML is just the wrong tool for that job.

HTML is great for when you have no idea what the user's
screen resolution is, very little idea what fonts they
have, how big their browser window is, whether they can
discriminate colours (and in our fairly small department,
two of my colleagues are red-green colour-blind, making
many syntax colouring themes worse than useless for them),
whether they can tolerate small text, ....