[erlang-questions] What about making sense?

[Joe Armstrong]

I think the problem with reorganising the documentation is basically
one of time and money.

The documentation that we have today was originally produced to
satisfy the internal needs of Ericsson. It was intended to be used
together with courses and on-site mentoring. OTP itself was designed
for a specific project, the AXD-301. The gen_servers, etc. were
designed to be used in "large projects". A lot of the call-backs (for
example, code_change, etc.) are irrelevant (and confusing) for small
projects. It was never the intention to design these as a
"one-size-fits-all" solution for all problems.

The intention was that every individual project would design their own
set of generic methods that were customised to their own internal
needs. We put hooks in the system to customise virtually everything
- people would write their own error_handlers etc. the problem is that
nobody ever does this, and many people just use behaviours in ways
they were never designed to be used.

Section 16.1 of my Erlang book is titled "The road to the Generic
Server" - the section starts "This is the most important section in
the entire book, so read it one, read it twice, read it 100 times
- just make sure the message sinks in".

This section develops an (almost) gen_server starting with a very
simple server and then applying 4 transformations to the original
to arrive at something pretty near to the gen_server. If you've
understood this, then understanding the OTP documentation should be
easy. But even better, you should be able to custom build you own
behaviours.

Back to the documentation problem. Funding a massive reorganisation of
the OTP documentation within Ericsson is currently inconceivable -
this is because the documentation is basically good enough for our
internal use. We want to spend time on things that generate revenue,
not documentation.

We are in no-mans land here. The problem is too big to do it with
small amounts of voluntary effort, and nobody is prepared to fund a
professional rewrite.

The few people who potentially could do the reorganisation are pretty
busy with other stuff.

What I would like to see is a big push on the books front.

Frasse/Simon and I have done the spade work with an "adequate"
description of the language and libraries. What we are lacking are
books describing the major applications.

Can somebody please write books about:

    - couchDB (in preparation)
    - ejabberd
    - rabbitMQ
    - mnesia
    - OTP
    - mochiweb
    - scalaris/riak

Or a book with one chapter devoted to each (mail Dave Thomas if you
want a publisher :-)

Since all the OTP documentation is nicely tagged up in XML
it might be possible to make a sub-language to assemble the
existing documentation into a different structure, with a better organisation.

Most of the real Erlang "experts" (ie those who make a living out of
the Erlang programs they write) - just don't have time to write
improved documentation - nor does it pay - the products are far more
profitable (the Guys at Klarna, for example, know enough to do this
but it is far more profitable for them to hack Erlang - and anyway
their company is doubling in size every year - or something daft)

Right now I'd like to see more application books - so get you pens
out.

/Joe

On Wed, Feb 17, 2010 at 4:52 PM, Michael Turner <leap@REDACTED> wrote:
>
>
> On 2/17/2010, "Robert Virding" <rvirding@REDACTED> wrote:
>
>>Without getting into the discussion how difficult, or not, it is to
>>navigate the Erlang docs one source of the problem is that all the
>>standard OTP libraries are proper Applications.
>
> People should think of the trigonometric functions as part of the STDLIB
> Application, just because gen_server is grouped in with them, in stdlib?
>
> What sense does this make?
>
>> 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.
>
> What sense does this make?
>
> What goal does this serve?
>
> The goal of making it easier to autogenerate the documentation?
>
> Well, I remember the days when we humans did a lot of things to make life
> easier for the system.  As I recall, it involved punching a lot of cards.
>
>
> -michael turner
>
>
>
>
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>
>