[erlang-questions] yet more ranting about Erlang docs

[Angel Alvarez]

El Jueves, 18 de Febrero de 2010 23:31:27 Richard O'Keefe escribió:
> Quite by coincidence, I happened to download Scalaris recently.
> It looks like an interesting and useful body of code, but it
> really is a textbook example of what's wrong with the JavaDoc
> Way of documentation.  The installation process gives you a
> directory full to overflowing with html files, every one of them
> displaying neatly as a screen full of, well, nothing useful.
> 
> This criticism does not apply at all to the architecture
> diagrams, which I found very helpful.  But that's not Edoc.
> 
> One thing this drove home to me is how many things we need
> to know about a component other than "here is a module here
> is a function".  Things about the environment.  For example,
> there's a Java interface for Scalaris and there's a Ruby
> interface, but what exactly is the *Erlang* interface?  It may
> be quite obvious to someone who has ever used any DHT from
> Erlang, but as someone who hasn't, it's not obvious to me, and
> it's not something about the code per se.
> 
> 
Still Mochiweb, Scalaris and others tend to be more useful snipets of code+ docs
that the erlang docs site on some areas.

Thereis a no man's land between the joe, and francesco books and the offcial docs making the whole thing
a kind of bermude's triangle where you risk sinking when you try to match some thing form one to the other.

Still a think there are many things on the docs that dont need close interventions of the otp people leaveing 
them free to focus on the code where the community can focus on the look n feel.

Let's look the recent iconv snipet on erl_nif and "erl resource's" stuff, how releases will take to appear something like this
on the "programming examples" users guide? Community can care of this better than OTP and far better than spreading 
knoledge here and there on the blogosphere... Even a wiki thing half-closed to a little amount of people covering some of 
you is more productive provided that we bare users can interact easily on the lists..

I have no prior expereince but on the PHP stuff but it got me some years to even think reading a php book
because i didnt need such a thing being very proficient on the php docs site...


-- 
Este correo no tiene dibujos. Las formas extrañas en la pantalla son letras.
__________________________________________

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.