[erlang-questions] yet more ranting about Erlang docs

[Michael Turner]

On 2/18/2010, "Angel Alvarez" <clist@REDACTED> wrote:

[snipping interesting proposal by Mats]
>Maybe we could pick a good collaborative tool and spread the
> work bettween many people...
>
>i think the current way (code -> XML -> docs?) is not so
>flexible for this approach...

Yeah, I know.  At the moment, on my way to trying to patch some docs,
I'm watching something called megaco take forever to build.  I have no
interest at all in megaco.  It's not remotely relevant to my immediate
problem.  I'm just rebuilding everything from scratch because a "make
release_docs" failed, saying it didn't have something called
"docb_transform", which (I had to figure out) is written in Erlang. 
I'm hoping that rebuilding everything gets docb_transform installed in
the right place.  But the dependencies of components on tools getting
moved to the right places aren't reliable in the Erlang build system,
in my experience.

OK, the clean build's done.  I try "make release_docs" again.  And
again, I get:

  docb_transform: command not found

*Sigh*.  I just want to start submitting patches to fix some of those
typos in the docs .... [Bangs head against edge of desk.]

>A community edition for the docs would allow OTP people to
>keep maintaining the old style docs and relaying on them
>while, a more open and fresh edition would grow up over 
>the time with collaborations from great erlang people and
>many comments, and addenda from the plain users base.

I like the idea.  But basically, Ericsson owns Erlang/OTP in every
meaningful sense of the term.  They just let us look at, and dink around
with, their code.  They don't even release their test suites, and
without those, nobody can realistically hope to take an independent
direction with the system.  Whatever the community does on Ericsson
reference material, it *must* be reflected back into their codebase, for
the foreseeable future, otherwise you'll have a fork that's steadily
growing incompatible with the Ericsson base reality.  And Joe lays it
out pretty clearly: unless a customer of Ericsson's is paying for it,
there's no funding within the company for anything sweeping.  So we
can't count on much help from that quarter.

>Ive seen many people blogging about diferent aspects of erlang
>and some of them writing good introductory materials for the
>language. Its just matter of organize the workforce in a more
>productive way..

I agree.  I don't know what the right solution is.  For now, maybe the
best we can hope for is to get better handholding, sometimes, for
working within the existing framework

-michael turner