[erlang-questions] What about making sense?

[Kenneth Lundin]

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?

I agree with you in that the documentation can be improved with better
descriptions and more examples and guidelines. There is also need for
good search facilities. We are working on both and we are releasing
the complete documentation sources plus support to build the doc. The
purpose with this is to make it possible for the community to help us
improve the docs.

I don't agree at all when you criticise the organization in :
Toplevel System documentation plus all the "applications".
Already on the introduction page at top-level (http://erlang.org/doc) it says
"Erlang/OTP is divided into a number of OTP applications. An
application normally contains Erlang modules. Some OTP applications,
such as the C interface erl_interface, are written in other languages
and have no Erlang modules. "

As everything is organized as "applications" in the source code tree
and applications actually are
groups of modules which are released and upgraded together it makes
perfect sense to structure the
documentation the same way.

An application can be a service that can be started and stopped or it
can be a library of passive modules with functions it does not matter.
The important thing is that an application is the smallest unit we
handle when it comes to deliverables. We always provide a complete new
version of a full application including documentation when we release
binary patches.
The documentation is treated the same way as code and is released
together with the code to assure
that you always have the documentation corresponding to the code.

Our experience is that this is a very efficient way to handle
documentation. We have no intention to change this. The documentation
can and will be improved anyway.

STDLIB and Kernel are unfortunately 2 basic (core) applications with a
very mixed content.
The criterias for what's in Kernel and what's in STDLIB  are unclear ,
we have discussed to
reorganize them some day but it has not been important enough to do
it. It will also introduce
potential incompatibilities.

Regarding the name "application" I think it is somewhat unfortunate
since everyone has an own idea
about what an application is in general. For example in Ericsson an
"application" is a complete product sold to end users. In Erlang it is
a group of modules handled together, possibly started as a service. I
think you have to blame Joe for naming it "application".
>
>> 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.

I don't really understand what you mean are the
conceptual/terminological confusions except maybe
application.

>
> What sense does this make?
>
> What goal does this serve?
>
> The goal of making it easier to autogenerate the documentation?

I don't understand what you mean here. Most of the documentation 95%
is handwritten.
We strongly believe in single source and many generated presentations
but this has no negative
impact on the actual 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
>
/Kenneth, Erlang/OTP Ericsson
>
>
>
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>
>