[erlang-questions] yet more ranting about Erlang docs

[Kenji Rikitake]

In the message <ee970b291002171819u6c1a89a9u23ebc0bce593596a@REDACTED>
dated Thu, Feb 18, 2010 at 10:18:45AM +0800,
Michael Richter <ttmrichter@REDACTED> writes:
> The documentation for Erlang is not great but so far I've not seen the "the
> source is the documentation" attitude that I've seen from the Ruby camp.
> There's more professionalism coming out of Ericcson than there is coming
> from the hobby hackers who make 90%+ of the Ruby camp.  Please don't start
> advocating a Ruby-style approach to docs.  It would really hurt to see
> Erlang go down that path.

Agreed.

One of the big differences between Linux and *BSD is the online manual
(shown by man command).  *BSD documentation available from the man
command is much more consistent and precise.  And that's the exact
reason why I do not want to convert my FreeBSD systems into something
Linux.

In my personal impression, Python online docs do fairly well and a bit
better than Erlang.  Erlang docs are cryptic but tolerable; at least the
doc writers try to maintain the consistency as Michael said above.

On the other hand, the requirement for how to describe a language has to
be changed, as time goes by, as the language itself and the usage
changes and evolves.  I think we need even more books, as Joe wrote.

One of the old examples I should note is that the uselessness of K&R
book for C language now; for example, when the 2nd edition came out in
late 1980s, there was not much attention on secure programming.
Harbison and Steele's "C: A Reference Manual" serves in a much better
way.  I no longer recommend K&R to C learners.

I see only two major books lately on Erlang (Joe's and
Francesco-and-Simon's), but even within these two books the
interpretation and description of the basic of Erlang completely differ.
And I think this difference is a very good thing.  I've already
preordered two more books about Erlang, and I hope more books will show
up.

And remember the borders between the books and the online docs are
disappearing, as more books are going electronic.

Just my 2 JPY worth,
Kenji Rikitake