Missing The Point Of Documentation

[Jayson Vantuyl]

Unless I'm grossly misreading your intent, I think that your response  
indicates the exact opposite to what you intended.

You seem to suggest that the reference manual is where people should  
start. This is dead wrong. Most people (even many good programmers)  
are not this way.

Documentation is just like user interface.  The best examples never  
put completeness before usability.  This is the reason that each  
Erlang application has a Users Guide (for usability), and a Reference  
(for completeness).

A fundamental problem with the Erlang docs is that they are very much  
organized in a way that fits the invisible architecture underlying the  
system, as opposed to being a helpful framework for communicating the  
intent of the design.

Someone has already noted the misleading language about anonymous funs  
that obscures the later reference to using the fun keyword to  
reference a non-anonymous function.  That's how this thread got started.

The issue is deeper, though.   Consider the information necessary to  
divine the relationship between erts, kernel, stdlib, sasl, proc_lib,  
gen_*, and everything else.  This is jumbled throughout a few guides  
and references in a way that is wholly incomprehensible to a novice.

Perhaps Erlang users (and FP users in general) are self-selecting to  
be more "reference manual" oriented.  I'm like this. I love nothing  
more than to go into wizard mode and pore over references until I  
understand the arcane secrets of a technology.  I just know that we  
can do better.

Go read the docs for Python and Django. They're better, by a  
longshot.  Heck, compare the oldest docs on erlang.org to the newest  
ones.  The direction to go is clear.

So, I'll take your smarmy RTFM, and raise you a STFU.  The whole point  
is that learning some of this is harder than it needs to be.  I don't  
care if the information exists, it needs to be easier to get.   
Impeding the cry for better documentation is a bad idea. Don't be that  
guy. See Wheaton's Law.

Sent from my iPhone

On Feb 16, 2010, at 2:19 AM, Anthony Shipman <als@REDACTED> wrote:

> On Tue, 16 Feb 2010 09:01:49 am Jayson Vantuyl wrote:
>> Oh, you can get links.  It's just that you need to know these things
>> are there. The average person that dives into the docs doesn't always
>> find these little corners.  There are qualities of good documentation
>> beyond mere existence.
>
> I find it useful to read through the reference manual first before  
> diving
> anywhere.
>
> -- 
> Anthony Shipman                    Mamas don't let your babies
> als@REDACTED                   grow up to be outsourced.
>
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>