[erlang-questions] node.js vs erlang

[zxq9]

On Friday 20 June 2014 09:02:29 Roger Lipscombe wrote:
> On 19 June 2014 11:57, zxq9 <zxq9@REDACTED> wrote:
> > Django users certainly don't. The Django documentation and the Python
> > documentation -- two non-trivial documentation projects if there ever were
> > -- are primary examples of how to speak directly to an open source
> > community in its own language while making things approachable without
> > dumbing anything down.
> 
> Personally, I find the Python documentation completely unapproachable.
> Too many details, too few examples.

I've never heard that, but you can hardly be the only one to feel that way. In 
your opinion, how does it compare to the Ruby or Perl documentation? Django?

I highlight the Python docs because they provide a complete tutorial and then 
pass to the library reference. The tutorial is much more decomposable than 
most (its not a walk-through of developing a complete project), and its 
surprisingly complete with regard to feature coverage.

You're right that the Python docs do not include many (any?) examples of 
complete projects (outside of the package/distribution section), but I believe 
they provide sufficient examples of specific features in isolation to be 
useful. This seems to be the exact thing you dislike about them. They have 
proven useful enough, anyway, that someone totally new to Python can jump into 
the code of an existing project and start learning on the fly. It worked for 
me (I understand this is a dangerous phrase, though).

Note the Python docs do not teach OOP or FP. I don't think the Erlang docs 
should, either.

Perhaps its that complete application-package type examples tend to occur in 
framework project documentation, not in language documentation. So, for 
example, after skimming over the Python tutorial one can work through the 
Django tutorial and publish a simple application from that. From there they 
tweak and modify and, viola!, have a trivial thingy running that does what 
they like.

But from there, of course, they run into some serious issues. ORMs simply 
don't work well for non-trivial cases. The excited coder now is forced to 
learn more about Python and to return to the docs, but this time to the 
library reference, not the tutorial. At some point he must understand more 
about the database bindings that are letting him talk to Postgres, and he 
finds relative uniformity among the Django, Python and psycopg2 docs (we can 
learn a lot from this detail, I think). Ultimately he must learn about 
Postgres itself, and that means learning about relational concepts if he 
didn't know them already -- and the Postgres docs fill the gap remarkably 
well.

This is a confluence of docs from totally different projects written at an 
appropriate level for their purpose. I can't imagine the core Erlang docs ever 
being so comprehensive without an absolutely staggering amount of effort.

Few people start with an initial goal of learning Ruby; they start with a 
desire to use Rails or work on Puppet or something else -- Ruby is an artifact 
of implementation. Few people (who get very far) start with an initial goal of 
learning Python, either; most start with a desire to use [any killer app in 
Python], and wind up learning a lot about Python along the way. I suppose the 
key is to find that killer project everyone wants to work on or killer 
framework everyone wants to use -- write it in Erlang, and diligently garden 
the docs of that other project.

-Craig

(Sorry for the long message. This turned out to be part live brainstorm and I 
don't have enough time to shorten it just now.)