[erlang-questions] yet more ranting about Erlang docs

Angel Alvarez <>
Thu Feb 18 12:40:14 CET 2010


El Jueves, 18 de Febrero de 2010 Michael Turner escribió:
> 
> On 2/18/2010, "Angel Alvarez" <> 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
> 
> 
> 
Well, So we maybe two main problems ahead

1) A more friendly way to the OTP docs *Just plain* no more not less, 
maybe some improvements on the final part of the toolchain will acomplish it. 
In other words IMHO we need a far better docs site predating PHP and the like

2) A discutible docs overhaul, as same people want to clarify or just evolve terms 
like aplications, stdlib and so on...


Number 1 is clearly needed to spread erlang and grow a good community of users and developers.

Number 2 reflects the nature of change erlang is taking as more and more areas outside telcos embrace erlang 
and many isolated groups start making foundation in parallel to the main concept so has to be taken
and led by the OTP team when they they find time and resources...


-- 
No imprima este correo si no es necesario. El medio ambiente está en nuestras manos.
__________________________________________

Clist UAH a.k.a Angel
__________________________________________
Artista -- (internet) --> Usuario final. Así los artistas cobran más y dicen menos paridas sobre lo que creen que es la piratería.


More information about the erlang-questions mailing list