[erlang-questions] node.js vs erlang

[Aaron J. Seigo]

On Thursday, June 19, 2014 01:30:02 Loïc Hoguin wrote:
> I am not even sure what triggers all these good comments about the
> nodejs documentation. Sure it has a 6 lines and 1 command example on its
> front page. There's no denying that. Then what? A link to API docs. I
> have *no* idea how people manage to learn how to use it. Surely by using

that's exactly the (non-intuitive) lesson to take away: you can have poor 
documentation and expect people to do lots of self-training and research BUT 
if you do these three "simple" things you can still be successful at spreading 
your tech:

0. attract: tell everyone what your product is really good at in a very 
simple, positive manner[1] 

1. be positive: greet potential adopters with positivity[1] and they will 
reflect that back 

2. have a "quick hook": give people something super quick and super easy to do 
at the very start. this gives them the feeling of accomplishment, even if it 
is completely trivial[3]. having tasted success (trivial as it may be) they 
will invest time/energy to get more.

by doing those 3 things, nodejs can have a steep learning curve and still 
succeed in getting lots of users.

conversely, you can have awesome documentation, but if you don't attract and 
quickly hook potential adopters, fewer people will adopt the technology.

personally, i think cowboy's docs are pretty damn good. but i can see how some 
potential adopters are being lost. if the three things above were implemented, 
without changing anything substantial in the documentation, more people might 
end up using cowboy / erlang. which would always be nice :)

tell you what: i've been looking for an area of erlang docs to contribute to, 
perhaps this is a good place to start. i'll try my hand at implementing the 
above 3-point-strategy in cowboy's docs and submit a pull request when i'm 
done ... always better to do than to the tell, right? :) i'll try and block 
some time for this in the next few days ....

[1] that usually means it isn't 100% complete and accurate due to summarizing 
and glossing over details to keep it simple; the performance benchmarks i 
referenced in a previous email are good examples of this
[2] the opening statement on the node.js website, and the first page of their 
documentations, are only about positives. they don't warn people about how 
tricky dynamic, async code that gets called non-sequentially can be , for 
instance.
[3] for nodejs, that is "An Example: A Webserver" bit on their homepage

-- 
Aaron J. Seigo
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20140619/802e2372/attachment.bin>