Advice

[Michael Turner]

On 12/14/2009, "Kenji Rikitake" <kenji.rikitake@REDACTED> wrote:

>Joe's Programming Erlang is like K&R for C for its terseness; and
>Francesco/Simon's Erlang Programming is more like "C: A Reference
>Manual" at least to me for its attempt to explain historical reasons of
>how Erlang evolves.  You may learn different things from each book.  I
>still learn many things from both.  Joe's PhD thesis is another
>thoughtful article to find out "why erlang".

Honestly, Erlang is so different from most languages that it's probably
a good idea to just keep reading everything by the experts, to help make
the concepts and syntax gel in your mind.

The book I've been *practicing* from, however, is Joe's.  I don't know
about Kenji's characterization of Francesco&Simon.  But K&R was, I
always thought, one of the best programming language books ever written,
and it's not a bad comparison, even if K&R is a little drier.  Then
again, I like brevity in a programmer's manual, within reason. YMMV.

>Erlang's Github repository, the Ericsson's reference manual(s), and the
>source code are of course precisely more in detail.

The Erricsson references online can't be beat for detail, but the
writing could use some work.

For example, I needed a "sleep" for something.  I searched on
"sleep".  I ended up in the timer module section, which says, in its
introduction, "All timer functions return immediately, regardless of
work carried out by another process."  No qualification, like "unless
stated otherwise".

At first I thought I was looking in the wrong manual section.  But on a
hunch (arising mostly from a distrust of the manual, having seen a fair
amount of confusing and low-quality description in it already), I looked
at timer:sleep/1 anyway.  Yep: there, at the end of sleep/1's
description, you see it: "Naturally, this function does not return
immediately."  Uh-huh.  Naturally.

It's not the only such problem in the reference manual.  I can see scope
for improvements almost everywhere I look, actually.  One of my earliest
questions to the list was, basically, "How can I help improve the
documentation?"  But maybe that got lost in everything else I was
saying at the time.

-michael turner