[erlang-questions] What about making sense?

[Michael Richter]

I think we have a lot of cross-talk going on here.

Item: Some people believe that the Erlang docs as they are interfere with
comprehension, partially because of inconsistent and unusual use of
terminology.

Item: Some people see no problem with the docs as they are.

The truth lies somewhere in the middle, I believe.

The docs are nowhere near as dire as some of the more vociferous
commentators are portraying them.  Are they ideal?  No.  Are they even good?
 Not really.  They are about average for this industry (which is a
condemnation of the industry's standards, not of the writers).  They are,
however, adequate.  *As references*.  If you already know what it is you're
looking for (or should be looking for) the docs as they stand are more than
adequate.

What they are terrible for is learning tools.  This is a problem in general
for Erlang, partially because it's a relatively new tool on the scene (the
public scene, that is -- I know it's been around for ages inside Ericcson)
and partially because it's a small community around it with only a very
small number of grognards who know it all.

On the learning front now we have two great tools (*Programming Erlang* and
*Erlang Programming*) with a third on the way (*Erlang and OTP in Action*)
for tutorial introductions.  These first two have been great for my picking
up Erlang, for example, but now another barrier has crossed my path.
 There's no documentation in between the "Erlang for Complete Newbs" stuff
and the "Reminders for the Grognards" stuff.

I think that is the failing of Erlang documentation at this point.  It's not
in tutorial-level information -- there's plenty of that and of very high
quality indeed (courtesy of Armstrong and Cesarini & Thompson).  There's
more of it on the way.  It's not in the reference-level information.  What's
there isn't ideal nor is it ideally organized but it's OK.  Better than some
languages, worse than others.  What's missing is information like overviews
of the available libraries (or "applications" in Erlang-speak), what they do
and a general idea of how to use them.  What's missing is good sample code
for these "applications".  Use case scenarios.  Where they are well-applied.
 Where they are not so well applied.  There is a great deal of stuff in the
Erlang/OTP distribution.  Here's a list of it:


   - appmon-2.1.10.2/
   - asn1-1.6.12/
   - common_test-1.4.6/
   - compiler-4.6.4/
   - cosEvent-2.1.7/
   - cosEventDomain-1.1.7/
   - cosFileTransfer-1.1.9/
   - cosNotification-1.1.12/
   - cosProperty-1.1.10/
   - cosTime-1.1.7/
   - cosTransactions-1.2.8/
   - crypto-1.6.3/
   - debugger-3.2.1/
   - dialyzer-2.1.0/
   - docbuilder-0.9.8.6/
   - edoc-0.7.6.5/
   - erl_docgen-0.1/
   - erl_interface-3.6.4/
   - erts-5.7.4/
   - et-1.3.3/
   - eunit-2.1.4/
   - gs-1.5.11/
   - hipe-3.7.4/
   - ic-4.2.23/
   - inets-5.2/
   - inviso-0.6.1/
   - jinterface-1.5.2/
   - kernel-2.13.4/
   - megaco-3.13/
   - mnesia-4.4.12/
   - observer-0.9.8.1/
   - odbc-2.10.6/
   - orber-3.6.14/
   - os_mon-2.2.4/
   - otp_mibs-1.0.6/
   - parsetools-2.0.1/
   - percept-0.8.3/
   - pman-2.7.1/
   - public_key-0.4/
   - reltool-0.5.2/
   - runtime_tools-1.8.2/
   - sasl-2.1.8/
   - snmp-4.15/
   - ssh-1.1.7/
   - ssl-3.10.7/
   - stdlib-1.16.4/
   - syntax_tools-1.6.4/
   - test_server-3.3.5/
   - toolbar-1.4.1/
   - tools-2.6.5/
   - tv-2.1.4.4/
   - typer-0.1.7.3/
   - webtool-0.8.5/
   - wx-0.98.4/
   - xmerl-1.2.3/

That is a pretty intimidating list for a newcomer to be faced with and there
really isn't a good overview of what each is, where each might be applicable
and how they interact with each other.  (No, a list on the left pane doesn't
qualify as guidance!)  Grognards who have been working with Erlang since
forever, I think, are forgetting that newcomers to Erlang are faced with a
lot of hurdles all at once.  Newcomers are often faced with their first
functional language.  They're faced with their first actor-based concurrency
model.  They're faced with an unfamiliar syntax that even old-timers have to
admit can be opaque and a bit strange.  They're faced with libraries--Oops!
 "Applications"!-- that don't play well together (edoc vs. typer vs.
dialyzer for example).  They're faced with all of this and get little to no
guidance short of community legend and lore to navigate through it.

I can see how this can be frustrating and how it can lead to the increasing
levels of heat showing up in this thread.  Unfortunately the heat is now
doing nothing but getting people on each side riled up, feeling embattled
and digging in as a result.  I'd like to ask for two things to help calm
this down:


   1. Grognards, please try and understand the position of a complete
   newcomer.  Imagine, for a moment, that you haven't been working with Erlang
   for years.  Look at the documentation that exists as if it were your first
   time.  Look at that list of "applications", the unusual terminology, the
   language that is pretty much unlike anything else out there in common use
   and ask (and answer) yourself honestly: is this sufficient for learning?  Is
   this helpful to a newcomer to the language?  If, as I expect, you answer
   "no" to these questions, ask yourself also what needs to change to make
   these helpful and sufficient and, more importantly, what processes can be
   put in place to speed along development of such tools by bringing in
   community input.
   2. Newbies (like me), please also try to understand the position the
   grognards are in.  Like you they are hired to be (or have made businesses to
   be) productive with code.  They're developers and not technical writers.
    Further the fruits of their labour are being given you at no (fiscal) cost.
    It is a bit unseemly to harshly criticize their (from their employers'
   perspective) non-productive labour when they, too, face the real world of
   software development with unrealistic schedules and deadlines, moving
   requirements and feature creep.  Be thankful for what is there already and
   perhaps have a little patience as the rest gets released and the processes
   get ironed out to have community input.

-- 
"Perhaps people don't believe this, but throughout all of the discussions of
entering China our focus has really been what's best for the Chinese people.
It's not been about our revenue or profit or whatnot."
--Sergey Brin, demonstrating the emptiness of the "don't be evil" mantra.