[erlang-questions] What about making sense?

[Robert Raschke]

On Wed, Feb 17, 2010 at 3:52 PM, Michael Turner <leap@REDACTED> wrote:

> > So when when the
> >documentation is organised around "applications", in one sense, it is
> >being entirely logical and consistent. Of course, until you are more
> >experienced and groked this it can be very confusing and difficult to
> >find things.
>
> But in the meantime, conceptual/terminological confusion impedes the
> learner, whenever he/she needs to resort to the Reference Manual.  Given
> that Erlang already poses quite a learning curve for some, this will
> reduce the rate at which people become "more experienced and grok
> this", and for that matter, it will reduce the number of people who
> even want to get that far with Erlang.
>

Learning Erlang _requires_ you to be open to new concepts and terminology.
Erlang is not Java. Erlang is not C.

The terminology is explained quite well in the Erlang documentation. But
effort on the side of the learner is actually mandatory. This effort lies in
reading the documentation and experimenting with the system to cement your
understanding of the text.

None of the programming language manuals I know are didactic texts. Well,
saying that, I've just remembered the original Smalltalk books; they're
pretty fine.

This does not mean we should not strive for great documentation. But simply
stating that the current set is not good enough won't change that. You don't
get quality that way. If you, or someone you know, can help with rearranging
the existing documentation such that it becomes qualitatively better, then
please pitch in. I'm sure your efforts would be welcomed.

I know that I am no good at writing documentation, but then I am also pretty
happy with the status quo ...

Robby