various documentation topics now

[Michael Turner]

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