Hay una serie de herramientas que son necesarias en cualquier ambiente de desarrollo, en esta serie de post, vamos a ver como crear un ambiente semi ideal para el desarrollo en equipos de desarrollo.Como primer topico vamos a hablar sobre la documentacion.

Seguramente les paso muchas veces que tuvieron que heredar algun desarrollo ya empezado, y tenian que perder mucho tiempo leyendo codigo y usando la aplicacion para entender como funcionaba y sin embargo siempre encontraban algo nuevo. Que genial seria poder leer la documentacion de como esta diseñado un software y poder entender, alcance, features, bugs, puntos de entrada, tecnlogias usadas, etc. Lamentablemente esto casi nunca pasa, y tenemos que hacerlo de la forma dificil y lenta. Pero nosotros podemos cambiar eso, e implementar politicas de documentacion para nuestros proyectos.

En estos sistemas podemos agregar documentos, screenshot, imagenes, especificaciones de instalacion, configuracion, librerias a usar, detalle de servidores, listado de grupos de desarrollo (en el caso que sean varios grupos), etc. Todo lo que puede servir para que una persona nueva en el grupo o alguien que herede nuestro codigo pueda entender como funciona leyendo la documentacion del desarrollo.

Como formato ideal de documentacion para este tipo de cosas, me parece que gana el estilo wiki. No solo tenemos wikimedia, sino que tambien contamos con Trac, Confluence, PbWorks, y muchos mas. Pero obviamente si les resulta comodo usar google docs, o archivos con formato Word o Excel tambien es valido, pero por experiencia siempre terminamos teniendo carpetas inecesarias con un monton de archivos que no sabemos de que hablan, y capaz que ya perdieron vigencia.

Aca les voy a contar de algunos proyectos interesantes que pueden usar para sus proyectos.

Mediawiki.

El mismo codigo que se usa para la wikipedia esta disponible para que nosotros podamos instalarlo internamente en nuestro servidor con nuestros documentos privados, funciona de la misma forma que la wikipedia y se puede descargar de http://www.mediawiki.org/wiki/Download/es, dentro de nuestro ambiente lo podemos configurar como una pagina comun y corriente.

Mediawiki es un producto open source. Y no hay que pagar por usarlo

Confluence

Esta es otra alternativa a mediawiki que se presume mas completa y facil de integrar con otras herramientas como Jira.
http://www.atlassian.com/software/confluence/overview

Lamentablemente este servicio es pago. Pueden usar los servidores de atlassian.com o pueden usarlos dentro de su ambiente. Cualquiera de las dos es viable, el producto es muy bueno a pesar de su precio.

Trac

Durante mucho tiempo use Trac, no solo por la wiki, tambien por su integracion con el repositorio de svn, la verdad es que hoy no me resulta comodo, hay muchas alternativas, y esta paso a ser de mis ultimas elecciones. Trac esta desarrollado en python, y tiene plugin para integrarlo con git y creo que tambien con mercurial y bazaar. Es open source y gratuita.

Uno de mis favoritos, es un servicio online, de documentacion de proyectos colaborativo, anda muy bien. La version gratuita es muy completa. Se puede pagar por algunos features especiales.
http://pbworks.com/

Basecamp

Es uno de los mas famosos, y brinda una solucion un poco mas amplica, no recuerdo si tiene wiki, pero si soporta compartir documentos, e integra muchas funcionalidades. Es un servicio pago mensualmente
http://basecamphq.com

Sin dudas mi primer eleccion, tanto para proyecto privados pagando el fee mensual, como para proyectos opensource, no solo integra git en tus proyectos, sino que ademas brinda la posibilidad de crear wiki, ticket, comentar parte de codigos, hacer comentarios de una review, trabajar con la cantidad de colaboradores que quieras, seguro, facil. Tiene bugtrucker. Git no seria lo que es hoy sin este servicio espectacular que crece dia a dia, PHP, el Kernel de Linux, Zend Framework entre otros decidieron pasarse a github para sus proyectos. Hoy yo tengo casi todos mis proyectos en github y funciona excelente. Como wiki cuando la documentacion crece quizas sea mejor decision pensar en mediawiki, o pbworks.https://github.com

 

 

Red Mine

Me olvidaba  de una de las mejores alternativas opensource, RedMine. Desarrollado en Ruby on Rails, es una excelente alternativa a Jira + Confluence, un producto super completo y libre.

http://www.redmine.org/

 

Conclusion

Hay otras soluciones, pagas y gratuitas para documentar nuestros desarrollos. Estas son con las que trabaje, en el proximo articulo vamos a tratar de elegir que software de control de versiones usar, y cual elegir entre tantas opciones nuevas.

No solo es importante configurar un ambiente sino tambien usarlo. Si implementamos algun sistema para documentar y no lo usamos no tiene sentido, es una buena costumbre documentar el codigo, y es algo vital para el futuro inmediato.