[erlang-questions] yet more ranting about Erlang docs

[Michael Richter]

On 18 February 2010 06:25, Joe Armstrong <erlang@REDACTED> wrote:

> If you're put off by strange terms, lousy documentation, incorrect
> examples, code that doesn't work, explanations that are plain wrong
> and idiotic specifications you shouldn't be a programmer.
>

Joe, I'm sorry, but this is likely the single most nonsensical thing I've
heard in a long time.  It pains me in particular to say this given how much
I've enjoyed most everything else I've seen from you, starting with your
book.

The reason all of this stuff exists is precisely because your so-called
"smart programmers" *tolerate* it (and in the worst cases actively *advocate
* it!).  Why did I put "scare quotes" around the term "smart programmers"?
Because I don't find it particularly smart to tolerate (or advocate)
practices which drain everybody's productivity time and time and time again.

I used to be an avid user of Ruby.  I've pretty much back-burnered it *
precisely* because of the dire documentation or, rather, more precisely,
because of the attitude toward documentation in the Ruby community.  (I
don't consider "Use the Source, Luser!" to be documentation.)  Every time I
tried to do anything non-trivial in Ruby I was faced with
productivity-draining exercises in frustration as one document said X,
another document said Y and the source, when you finally took the plunge,
said A, B and C instead.  (For today.  Tomorrow it might say B, C and D.)  I
would find myself increasingly working on things other than my problem
domain when I really wanted to work on my problem domain.

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.

-- 
"Perhaps people don't believe this, but throughout all of the discussions of
entering China our focus has really been what's best for the Chinese people.
It's not been about our revenue or profit or whatnot."
--Sergey Brin, demonstrating the emptiness of the "don't be evil" mantra.