[erlang-questions] yet more ranting about Erlang docs
Thu Feb 18 04:11:41 CET 2010
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.
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
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
And remember the borders between the books and the online docs are
disappearing, as more books are going electronic.
Just my 2 JPY worth,
More information about the erlang-questions