[erlang-questions] What about making sense?

[Richard O'Keefe]

On Feb 19, 2010, at 9:30 PM, Michael Richter wrote:
[much that I agree with]

Let me say that I love Erlang and greatly respect those who have
developed it, and that I have met with nothing but kindness.  As
I haven't paid a single farthing for the Erlang documentation, I
should start by saying that as reference material, it works well.

But the only way I ever discovered stdlib was by expanding every
item in the navbar until I found it.  And that's despite knowing
that the bundle in question was called 'stdlib'.    I have found
the hardcopy manuals a great resource because my approach to any
book-like material is to try to read it cover to cover.  There's
a very different problem for someone trying to read online stuff,
and it's basically an information retrieval problem.

Here's an example. I just stumbled across the 'slave' module. If
I had been looking for it I would not have looked for 'slave'; I
would have been looking for "create remote node".

Here's another aspect.  For some reason the click-on-a-lot-of-
nested-folder-icons interface seems to have crossed from Windows
into the real world (:-).  But a rigid hierarchical tree is NOT
a good model for documentation.  For example, if I want to read
about "database applications", I really really want ETS, DETS,
ms_transform, and a bunch of other things to be visible at the
same time, not just odbc and mnesia.  A hierarchical structure is
legitimate for printed material, where you don't want a lot of
duplication.  But in a hypertext system, it's much less useful.

Reverting to 'slave', the description for the 'slave' module
never actually defines what a slave node IS.  We learn that
  - a slave node dies when the master dies
  - a slave node needs to have the same Erlang distribution in
    the same place as the master
but what OTHER differences are there between slave nodes and other
nodes.  For example, if I have two nodes A and B in a cluster and
node B creates a slave C, can A talk directly to C?  When is it
better to create a node as a slave than otherwise?  When is it worse?

This is what I have against the JavaDoc way, now faithfully copied
by Erlang programmers who wouldn't dream of copying Java.  It
strongly encourages a focus on *part* of the documentation.  A
useful part, but *only* part.  In fact, precisely the part that you
might be able to figure out for yourself by reading the code.

A good guideline for anyone working on Erlang documentation, whether
in the core Erlang/OTP team or elsewhere, is to constantly ask the
question "what do programmers need to know about using this module
that they WOULDN'T be able to find out by reading the code."

The documentation for ms_transform, which I also stumbled over by
accident one day, is actually pretty good that way.  It tells you
what it's _for_, why it's useful, with examples of how to use it.