Missing The Point Of Documentation
Tue Feb 16 12:34:45 CET 2010
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
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
> 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
More information about the erlang-questions