[erlang-questions] Re: What about making sense?

[Joe Armstrong]

I've been thinking about documentation/books for years now.

One thing that documentation and books does not capture is the order in
which we write a program.

A book with a code example presents the final result of a process. Not
how we arrived at the result.

When I write *any* process I always start with something like:

loop(...) ->
    receive
         Any -> io:format("got:~p~n",[Any]),
         loop(...)
   end.

it's always the same. I then run the program and see what messages
arrive at the receive loop. I then add patterns that match the messages
that arrive.

As I develop the program I work in small steps - adding one message at a time
and testing as I go. When I'm ready and the program is developed I might
remove the "Any -> ..." bit.

Seeing the final result give no clues as to the order in which things were
done. Each micro step can have a deal of thinking behind it.

Can this be described in words at all? - I doubt it. I really like Utube videos
that explain how to do things in some domain. You can stop and replay them.
A video with a detailed commentary seems then best way to do this.

This is why teaching is better than reading a book - when I teach I live code
and the students see each step. When you read this there should be no typos,
but as I type it I make mistakes which I then correct, but you don't see this.

The beginner sees the finished result - not the process - and can be
frighted off by the thought that "I can't do this: the result is so
perfect - I make
loads of mistakes" - that's because they don't see the mistakes.

When I wrote my Erlang book, Dave Thomas was my editor, he sent me long
detailed comments. A single paragraph could elicit a food of response.
His comments had spelling errors, seeing him make spelling errors
elated me. I was overjoyed - the great Dave Thomas, best selling
author, could make spelling errors, he was human like me. He said in
some mail "we employ proof readers to fix stuff like this" - joy
unbounded.

Books - and printed documentation - no matter how good - cannot illustrate
process - *the exact order in which I did things any why* - teaching
is the ultimate
answer. The students can see the order and *ask questions* (so we can
change the order). Second best are videos - but you can't ask
questions. Third are books.
Fourth is documentation. Fifth is the code.

I greatly sympathises with those who say "I can't understand
documentation". Documentation is written for those who already
understand - and is no a vehicle for understanding itself.

"Read the code Luke" is even worse - even If I could understand the code
(which can sometimes be *extremely* difficult) I have not idea at all
what it is *supposed* to do  only what it does. I consider this
unprofessional.

The work is not finished until the code is written, proved correct, documented,
and the courses given and the knowledge passed on for future generations.

This is beyond state-of-the-art (especially the proved correct bit)

So If you *really* want to learn, try things in this order:

    1) go on a course
    2) watch a video
    3) read a book
    4) read the documentaion
    5) read some code

My kids go to school to learn stuff - I wouldn't just chuck a program
listing at them and expect
them to understand it.

/Joe

On Sat, Feb 20, 2010 at 2:44 PM, Steve Davis
<steven.charles.davis@REDACTED> wrote:
> Hi Michael,
>
> I certainly respect your position, and as with many such discussions, I can
> only give my own experience.
>
> I do remember reasonably clearly being a newb. Actually, it wasn't that long
> ago (2008)! I remember starting by reading the Getting started section, and
> then going through the Erlang reference manual and programming examples. I
> also remember having to re-read a good deal of the OTP stuff before I truly
> "got it".
>
> When I started with C, many years ago, I managed to get by with two
> additional books. When I started with Java (even in the era of Java 1.1) I
> was forced to read about 20+ additional (and highly verbose) books beyond
> the documentation. When I started with Erlang, it found it sufficient to buy
> just one book (Joe's book) in addition to the docs - and the docs remain my
> primary reference.
>
> I am not saying there is no room for improvement in the docs; for example,
> finding something quickly can indeed be a pain (though frequently, it is
> not). When you do find what you need the manner in which it is written is
> almost always highly concise and accurate (though not always). The flaws in
> the docs currently are really more at the level of inconvenience than fatal
> flaws.
>
> It is certainly possible that I really have "lost touch", or that I'm just
> comparing the pain of Java-world to the relief of learning/using Erlang. But
> that's not my call to make.
>
> One enormous benefit of Erlang/OTP as a platform for me is that it covers so
> much (not all!) of the functional space requirements we face as application
> developers without any required reliance on third party software (and having
> to read/cope with all the documentation you need for those also).
>
> Best regards,
> Steve
>
>
> Michael Richter wrote:
>>
>> I respectfully disagree.  I humbly submit further that you are not doing
>> what I suggested by looking at the existing docs with a newb's eyes.
>>
>
>
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>
>