[erlang-questions] What about making sense?

[Joe Armstrong]

On Fri, Feb 19, 2010 at 9:30 AM, Michael Richter <ttmrichter@REDACTED> wrote:
> 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.

Correct - the OTP documentation was designed for a target audience
of internal Ericssomn folk who has already been on a course, and who could
stop me or Uffe or Robert, Klacke etc. in the corridor and ask us a question

> 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.

Great - the books were designed for beginners - my target audience
were "folk who were proficient in Java and had no exposure to FPLs"
In fact we got some tame Java programmers to read few sample chapters
before deciding the final level of complexity.

So far no surprises - the OTP documentaion and books meet *exactly* the
requirements we had when we started the projects.

What's happing now is a shift in the requirements.

I'd like to ask some pointed questions, the results will influene what happens
next.

Can anybody point me to a good free survey site - I want to ask questions
and get a histogram of the replies. If we can first find out *what* you want
we can then figure out *how* to achieve it.

The first question is about books. I can think of the following titles:

    1)  Real beginner - lower level than the Prag or O'reilly books, chatty
         tone

     2) Theory - a theory of concurrency oriented programming - why
         share-nothing agent programming is good. Design patterns.
         distributed algorithms. How does leadership election work, DHTs etc
         academic in tone.

     3) How to books - take one subsystem and document all the nitty
gritty stuff.
         Candidates

         - mnesia
         - yaws
         - ejabberd
        - asn1
         - [you name it]

     4) How to book, with emphasis on setup. Lots of details
         where to fetch, how to compile etc.

         (not generic - with sections for Ubuntu, OS-X and windows 7)

         one chapter/per topic

         - ejabberd
         - mochiweb
         - scalaris
         - nitrogen
         - [you name it]

     6) Case studies (business)
         Not sure if this is even possible.
         I'm thinking the business case behind sucessfull Erlang companies.
         What they did and why (technical stuff)
          This is the book I'd want to read - but much is still
commercially sensitive

     7) case studies (technical)
          How was X built and why? Give the history. What worked, what failed.
          Basically interviews with the lead developers of each X

          For X in
               yaws
               ejabberd
               [you name it]

     8) Other
          [you name it]

Comments

 4)  and 7) seem to be the easiest to produce - just decide on the chapters
(please suggest topics) and recruit one volunteer per chapter (no
problem with domain experts here) and an editor and some reviewers.

3) is pretty difficult - very few people know everything about a particular
sub-system - and even if they do might not want to spend thousands of
hours documenting it - sales would be small anyway (I suspect)

1) and 2) are possible

7) might make a nice web site - need not be a book

I'll put these question on a survey site, so people can vote, if somebody
can suggest one - or can we do this on the main erlang site???

Cheers

/Joe


> 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:
>
> 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.
> 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.
>