[OT] documentación rails

Hola,

Muchas veces se preguntan en la lista cosas que están directamente en la
documentación de rails (en los rubydoc que están en el fuente y que
podéis encontrar online en [2])… pero es cierto que a veces esa
documentación es incompleta, o está obsoleta, o sería mejorable, etc,
etc, etc…

Como esto sigue siendo un framework open source, las mejoras tienen que
venir de mano de la comunidad… vamos, de nosotros. Lo malo de esto, es
que normalmente uno contribuye un parche cuando algo no le funciona, o
no funciona como le gustaría, y cambiamos el código… pero no es
habitual que alguien mande un parche solamente para completar
documentación que no existía o era poco precisa porque al fin y al cabo,
al que descubre el problema en la documentación, “ya no le hace falta”.

El problema con esto es que, o llevas trabajando con rails mucho tiempo
y te conoces todos sus trucos, o te pones a ver el código para ver cómo
funciona, o estás perdido… con lo que la barrera de entrada al
framework se va poniendo más alta.

Hace unos meses, Pratik decidió montar un branch separado exclusivamente
para trabajar en mejorar la documentación. Podéis ver información sobre
esto en [2], [3] y [4]. Se trata simplemente de mejorar los RDocs y
aprovecharse de Git para que el proceso de revisión sea más simple.
Además, una vez tus commits se han incorporado a la rama principal, ya
te dejan permisos de Commit, con lo que el proceso es bastante cómodo
(aunque tengas permisos de commit, cada cambio se sigue revisando antes
de hacer merge con la rama principal de Rails).

Además de la iniciativa de los RDocs, se ha puesto en marcha otra
iniciativa que consiste en escribir guías enfocadas a alguna parte del
framework (caché, migrations, active record, plugins…) que tienen un
poco más de chicha. En este caso también se puede contribuir de forma
sencilla, y además te puedes llevar algunos premios por hacerlo. Puedes
encontrar más información sobre esto en [5] y [6].

Podéis ver en [7] el estado actual de las guías. Algunas, la de
migrations por ejemplo, están bastante avanzadas.

Bueno… pues eso… que ahora cada vez que tengáis que preguntar cómo se
hace algo que no está documentado, o cuando veáis algo en la
documentación que es incorrecto, es muy fácil contribuir y hacer que
el framework y la comunidad sigan avanzando. Por cierto, confieso que yo
lo tengo como asignatura pendiente y todavía no me he puesto a ello,
pero cualquier día de estos empiezo.

Saludos,

pepito grillo

[1] http://api.rubyonrails.com/

[2] http://groups.google.com/group/rubyonrails-core/msg/71e7460d41bdfd89
[3]
http://weblog.rubyonrails.org/2008/5/2/help-improve-rails-documentation-on-git-branch
[4] http://github.com/lifo/docrails/tree/master

[5] http://weblog.rubyonrails.org/2008/9/4/guides-hackfest
[6] http://hackfest.rubyonrails.org/guide


javier ramírez

…i do ruby on rails development in madrid, spain, at
http://www.aspgems.com
…you can find out more about me on http://formatinternet.wordpress.com
and http://workingwithrails.com/person/5987-javier-ramirez

javier ramirez wrote:

Podéis ver en [7] el estado actual de las guías. Algunas, la de
migrations por ejemplo, están bastante avanzadas.

[7] http://guides.rails.info/index.html

p.s. esto ha sido una demo para que veáis lo fácil que es añadir
información que se omitió por error :wink:


javier ramírez

…i do ruby on rails development in madrid, spain, at
http://www.aspgems.com
…you can find out more about me on http://formatinternet.wordpress.com
and http://workingwithrails.com/person/5987-javier-ramirez