[erlang-questions] Apology

[Richard A. O'Keefe]

On 20/09/16 8:18 AM, Loïc Hoguin wrote:
>>
> As for the documentation being very clear, it's very subjective. Nothing
> is ever "very clear" to everyone.

Fair point.
There are actually two issues, of course.

FINDING the documentation is the first thing.
Searching for "Erlang documentation" quickly turns up
https://www.erlang.org/docs.
That says
   <a>Erlang Reference Manual - User's Guide</a>
   A user's guide System principles and efficiency guide
which looks like an editing error.  If you follow the
link you find the reference manual, not the system
principles or efficiency guide.
A reference manual and user's guide being different
things, it would be better if this said something like

   <a>Erlang Reference Manual</a>
   Defines Erlang's syntax, built-in data types,
   preprocessor, error handling, processes, and more.

It would also be better if when you clicked on the link
it didn't say

   Erlang Reference Manual User's Guide

(which sounds like a user's guide to using the reference
manual) but something like

   Erlang Reference Manual
   {An abstract}

because the eye is drawn to the big blank space where
there's just a copyright notice, rather than to the navbar.
I can't speak for anyone else, but whenever I go to that
page I have several nervous seconds while wondering if I've
come to the right place.

I personally find it confusing that "Escape Sequences"
comes after "Boolean" rather than after "String" or "Atom".

Perhaps the most helpful thing in
https://www.erlang.org/docs
is
   <a>Learn You Some Erlang for Great Good!<a>
   Learn You Some Erlang for Great Good! by Fred Hebert
   is a beginner's book about Erlang, published in 2013.
   It is available in paper copies and online.

I have a copy of that book.  While it is a good book
for beginners, it isn't just for beginners.  I have to
be honest here: when it first came out I *hated* the
title.  Stupid, stupid, stupid.  "Don't judge a book
by its cover!"  Actually reading the book taught me,
well, not exactly stuff I hadn't found elsewhere, but
how to *use* a lot of stuff I hadn't bothered with.
Someone who reads that book will not be a beginner for long.

We are blessed with a lot of good books about Erlang.
I don't want to rank them.  But I do think that the
documentation page might want to draw special attention
to this book because people CAN read it on-line.  For
example, three clicks get to you an explanation of strings.

The second issue is UNDERSTANDING the documentation when
you find it.  The problem for writers is striking a
balance between being concise and being patronising.
I remember putting a lot of effort into writing a
document for the BSI/ISO Prolog committee explaining a
particular issue and some alternatives, and being told
that it had been completely ignored because it was too
long.  There's a series of books, originally "The Little
Lisper" which I personally experienced as offensively
patronising (and so culture-bound it wasn't funny, though
it tried to be).  Yet for many people it was an EXCELLENT
introduction to Lisp and Scheme and they loved the humour.

The current reference manual tries to be reassuringly
informal (for beginners) and timesavingly brief (for
experienced users).  Perhaps these rôles should be
split between two different documents?  Or maybe an
idea from MTW https://en.wikipedia.org/wiki/Gravitation_(book)
could be adopted:  the text of that book is divided into
"Track 1" (beginner level) and "Track 2" (more advanced)
and the corners of the pages are coloured so you know which
is which.  (About 35 years after buying it, I'm still on
track 1.  Sigh.  It's a great book for long flights: I am
guaranteed *never* to finish it.  Sigh.)

Hey, maybe we could get Fred Hébert to write the
"Erlang Reference Manual for Beginners" (:-).