[erlang-questions] Is there a good source for documentation on BEAM?

[Fred Hebert]

That depends. As a personal rule, I see 3 general levels of documentation:

1. Beginner guide/tutorial
2. Reference Manual
3. Architecture

1. The first type is the one that scratches the surface, gives a few usage
examples, and generally helps newcomers and users.

It explains why you'd use the library/module/thing, and directs in how to
do so. It holds the user's hands so they can quickly solve whatever problem
they have.

The raw version of this is either reading test cases or Open Source code
that uses the product.

2. The reference manual is a listing made to help those who already know
the item. It details everything but gives few explanations. It can be used
to deepen one's knowledge, but won't do any hand holding, or very little.

EDocs and the general javadoc-style stuff fit this well.

The raw version of it is 'read the source, Luke'. It works for experienced
users, and is of nearly no use to others.

3. Architecture is the doc that explains why the app was built the way it
is, a view of how it works from 10,000 feet. It shows how to understand the
app were you to dive in its source.

This kind of doc explains the rationale of some choices made, and is
especially helpful to developers or contributors to your code, so that they
do not undo future plans, respect trade off decisions you made, and know
where to dive in to extend things without causing headaches to anyone.

I know of no raw version of this; it's experience and in-depth knowledge of
the product's life. Writing this doc is often vital to raise the quality
and relevance of contributions received.

----

In my opinion, you don't have great documentation until you covered the 3
aspects. You can have poor, decent, or good docs without all of them, but
greatness requires to cover all bases.

A self-proclaimed complete book, in-depth tutorial, or course, should touch
all 3, for example.

Understanding your code well and making it self-explanatory sadly rarely
helps with more than one out of 3 points.
 On Jun 1, 2012 12:35 PM, "Robert Virding" <
robert.virding@REDACTED> wrote:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20120601/57b6d9c6/attachment.htm>