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

Basecamp

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.