[erlang-questions] Re: various documentation topics now

[Michael Turner]

On 2/16/2010, "Dale Harvey" <dale@REDACTED> wrote:

>I think the community has done pretty well with learning tools, we have
[snip]

True, but a bit of non sequiter for this discussion, which is mainly
about Ericsson Official at this point.  And that's a target that all of
the sources you mention will need to track from release to release. 
Tutorials necessarily scratch the surface, or at least they don't dig
very deep, and when you really get going you need to dig deep sometimes.
 It's nice that there's a lot of introductory material now, but
diversity of sources spreads effort thinly sometimes, where
concentration might be better.

Trapexit?  Yeah, well, maybe I had a bad initial experience: I got all
excited about the pretty diagrams for the neural network example
ostensibly worked through there.  When I tried to do it, I found that it
wasn't even finished, was missing parts of the code.  Contacting the
author got me nowhere.  Asking on this list got me nowhere.  That's
time out of my life I can't get back.  It makes Erlang look cool, I
suppose, to feature a neural network developed in a fairly polished
tutorial style.  But certain kinds of intellectual lip-gloss are hardly
better than intentional deception.  I reported the problem, but nobody
bothered to even take the page down.  Maybe I should have done it.

-michael turner


>On 16 February 2010 12:49, Michael Turner <leap@REDACTED> wrote:
>
>>
>> On 2/16/2010, "Attila Rajmund Nohl" <attila.r.nohl@REDACTED> wrote:
>>
>> >2010/2/16, Michael Turner <leap@REDACTED>:
>>
>> >> Reference manuals are typically huge, Erlang/OTP's is no exception,
>> >
>> >Somehow my problem with the Erlang reference manual was always that
>> >it's not huge enough.
>> [snip]
>>
>> I'm reminded of the anecdote about the film editor who somehow made a
>> "director's cut" release more interesting -- and thus *seem* shorter
>> -- than the original theater release, by adding some cuts back in and
>> rearranging things a little, actually increasing the running time by 20
>> minutes in the process.
>>
>> But whatever we do, let's not blame the fine folk at Ericsson.  The
>> documentation has only been up at github for little while now.  And
>> Erlang obviously has a lot more Europe penetration than in the (native)
>> English speaking world, aside from being a small minority programming
>> language anyway.  So there's a shortage of people who can really fix it
>> up nicely on a volunteer basis, and probably not much internal financing
>> for the job within Ericsson.
>>
>> I know that I should spend less time on this list and more on
>> contributing documentation patches -- typo fixes first, then more
>> detailed contributions as my knowledge of Erlang improves and people at
>> Ericsson trust that I can improve things.  Every day, I see something.
>>
>> Apart from that, well ... what Jayson said.  (But, um, terrestrially
>> rather than ballistically.)  He's right.  Good docs are an important
>> gateway to a language.  Erlang has taken an odd path to open source, one
>> that perhaps means that a lot of somewhat undercooked draft
>> documentation has tumbled out into public view.  And it's been a
>> relatively small and localized community, making documentation not quite
>> so important for a while.  I mean, I can't believe I'm on a mailing
>> list where a few co-architects of the language are fairly regular
>> contributors.  It's like back when you'd get Dennis Ritchie (in
>> person!) copping to having screwed up bitfields on comp.lang.c in the
>> early 80s.  I like it.  You probably do too.  But you have to admit,
>> ultimately, Erlang won't succeed without a education/communications
>> strategy as scalable as the language itself.  Better reference materials
>> will be an absolutely essential part of that story.
>>
>> -michael turner
>>
>>
>>
>> ________________________________________________________________
>> erlang-questions (at) erlang.org mailing list.
>> See http://www.erlang.org/faq.html
>> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>>
>>
>
>