[erlang-questions] yet more ranting about Erlang docs

[Ulf Wiger]

Jayson Vantuyl wrote:
>
> Unfortunately, the deployment stuff seems to have critical mass
> outside of Ericsson, with things like rebar.  These projects don't
> have much inclination to support the existing deployment stuff, so it
> is unlikely that Ericsson will ever adopt their work.

Actually, rebar makes heavy use of reltool, so there is little
conflict there.

>> Would you hire a "smart programmer" who rejected a language because
>> the documentation was crap?
> I'm still here, right?  Look, smart programmers don't need to spend
> all of their days wrestling with minutia and mundane tasks because
> their tools are too ill documented and obtuse (which prevents easily
> developing better tools as well).  Smart Programmers don't reject a
> language because the documentation is crap.  They might do so because
> the people behind the language refuse to make it better.  Don't be
> that guy.  See Wheaton's Law.

In fairness to Joe, he did list a number of things done
by the OTP team lately to improve the documentation build
chain, and make it open so that the documentation can be
improved by the community just like the OTP code now can.


> While limited resources are perhaps the best reason for the
> documentation not being better, please do not trivialize the
> importance of documentation.

Again, I'd like to point out Joe's track record.
Far from trivializing the importance of documentation
he has repeatedly stressed the importance of it. Also, the
fact that Joe has authored two of the three existing books
on Erlang could also be taken as a hint that he values the
written word.

> Just say:
> 
> * It takes time and money. * Our customers mission critical needs are
> always our top priority. * When we can make it better, we want to and
> we will. * We accept patches.

I thought this was pretty much the main point that Joe
tried to make in the first part of his email.


> Better yet, see if you can find someone in the community that has an
> idea for a way to organize the docs that makes sense, and then figure
> out how to roll the information in the old docs into the new ones.

The vital first step needed to enable this was to make the
documentation sources and tool chain open. This has now happened.
Let's see if that (considerable) effort pays off. It is likely
to take a little time, though.

> Heck, if you want to be really crazy, try re-imagining the structure
> of your deployment "applications", documentation "applications", and
> runtime "applications" into something coherent.  I think that this is
> where we need to go, but if we don't know where we're going, we'll
> never get there.

Since this seems to be "defend Joe day" (uhm, night), I could also
point out that Joe posted a message on this list a while ago where
he did /exactly that/. He received criticism by people who felt that
the existing framework actually works well and does not need a
complete overhaul. I didn't weigh in on that discussion, but am
also of the opinion that OTP's application and release framework
is for the most part excellent and deserves gradual improvemets
rather than dismissal. Some of the names may have been a bit
confusing in retrospect, but I think accepting that (small)
obstacle in the learning process is a fairly small price to pay.

BR,
Ulf W
-- 
Ulf Wiger
CTO, Erlang Solutions Ltd, formerly Erlang Training & Consulting Ltd
http://www.erlang-solutions.com
---------------------------------------------------

---------------------------------------------------

WE'VE CHANGED NAMES!

Since January 1st 2010 Erlang Training and Consulting Ltd. has become ERLANG SOLUTIONS LTD.

www.erlang-solutions.com