Language Bindings for Erlang Again (Opinion)

[Andrew Lentvorski]

Joe Armstrong (AL/EAB) wrote:

>> OTP cannot be picked up in 4 to 8 weeks because its 
>> documentation sucks.
> 
> Now I could write several pages here, since I wrote a lot of the
> documentation
> I would find it rather helpful to know which part "sucks" - please send
> me a list
> of errata or tell me exactly which parts of the documentation you are
> having problems
> with.

"Sucks" is probably too strong a word.  It connotes incorrect 
information.  "Unhelpful" is probably closer.  If you know what you 
need, it is okay.  If you only kinda vaguely know what you are looking 
for, it is problematic.

The main questions the current documentation does not answer are:

Why do you use module/feature/application X?
When do you use module/feature/application X?
When do you *not* use module/feature/application X?
What are the important features X which you want to pay attention to?

Your tutorial code is better documentation than the reference manual 
because it provides *context*.

Learning Erlang from the reference manual is like learning English by 
reading a dictionary with very few example sentences.  It can be done 
with enough motivation, but there are much better ways.

You (IIRC) posted a very nice comment about OTP explaining that 
gen_server was meant to organize the code for a large project to provide 
an overall structure and is probably overkill for a single person.

That's a tremendously useful insight that is completely missing from the 
documentation.

How about basic idioms in the language?  a la. the Python and Perl 
cookbooks.   Where are they stored?  Who has them?  What are the good 
idioms?  What are the bad idioms?

Why do I have to go to the Scheme cookbook to find the Erlang cookbook? 
  Why isn't that in the Erlang wiki?  Or linked directly from the Erlang 
website.

Is the Erlang wiki even updated anymore?

Why is search broken on the mailing list?
http://www.erlang.org/cgi-bin/marc-search.cgi?ml-archive%2Ferlang-questions

All of this leads to the sense of corporate abandonware when you start 
digging unless you dig deep.

Thank heavens for everybody on the mailing list.

> IHMO the *amazing* thing is the large number of people who have
> understood the documentation
> and built pretty impressive system *without ever asking any questions on
> this list*
> 
> These are the people who's first question to this list is something like
> "I have set up
> a 20 machine cluster, and a fragmented mnesia table, and when two of the
> machine crash
> I need to ..." - and you wonder - how the heck did they get that far
> *without* asking any 
> questions - well done guys - at least *somebody* must have read the
> manual. 

Yes, it is amazing.

I managed to compress 12,000 lines of Java code into about 1,000 lines 
of Erlang code.  Does that make my code good?  No.  Does that mean that 
I am using the language properly?  No.  How many bugs am I going to have 
to kill because the architecture I chose does not really quite map onto 
Erlang structure?  Quite a few (already I'm thinking about rewriting one 
section now that I understand things better).

>> Why do I use OTP?  When do I use OTP?  When do I *not* use OTP?
>>
>> A reference manual like we currently have is merely a first step. 
>> Something on the list like "Guru of the Week" was for C++ 
>> would be useful and wouldn't require the publication of a book.
>>
> 
> What would you like - what I am planning is an interactive version
> of *all* the documentation - ie every document becomes a "forum"
> where you can interact with the documents.

We don't need to interact with the documents; we need to interact with 
the experts.

Guru of the Week (GotW) was an ongoing discussion in 
comp.lang.c++.moderated (I think) where some of the experts would pose a 
question on the mailing list about something they bumped into while 
coding and then detail their attempts to solve it.  Surprisingly, many 
of the questions considered turned out to be much more involved than 
expected.  By watching the experts (and how they solved things), good 
C++ style got disseminated.

>>>> I'd like to see some good books on "modern erlang/otp"
>>>> for example. 
>>> Yes, something like Practical Common Lisp, only for Erlang.
>> Ayup.  That would be nice.
> 
> Books are in the pipeline

Cool.  I'd be happy to help proof.

-a