Como documentar proyectos: ¡Wiki al rescate!

Cualquiera puede colocar información aquí, de manera fácil y con pocas restricciones. Es de esa manera que se mantiene relevante

Le voy a mencionar uno de los aspectos menos glamorosos de todo proyecto de software, incluso menos glamoroso que hacer pruebas de calidad (testing) al código: Documentar.

Si, documentar. A nadie le gusta documentar, por las siguientes razones:

• La documentación se vuelve obsoleta desde el momento que la escribes: El software cambia, salen errores, hay más o menos funcionalidades. El API cambia también si lo que se escriben son librerías.
• No hay tiempo para hacer documentación: Al menos que tengas un escritor tecnico (tecnical writer) seguramente un desarrollador es quien se encarga de esta tarea. Por supuesto no es la única cosa que tendrá que hacer y al menos que sea la documentación de el usuario esta fase tendrá una baja prioridad.
• No es bien visto: Por muchas razones: Hay cosas más importantes que hacer (código, pruebas, soporte) o el "know how" no debe salir de un grupo selecto. Todo esto es un problema de percepción, sobre todo la de que el know how no debe salir de un grupo selecto de personas (por cierto, la compañia que hacia esto tuvo que cambiar su nombre por recomendación de los inversores).
  

¿Así que hacer?. La documentación debería recibir el mismo tratamiento que el software, ya que esta evoluciona con el tiempo, adermás de que debería ser el resultado de un esfuerzo colaborativo. Y sobre todo, debería ser fácil de modificar y buscar.

Bueno, todo eso suena como un Wiki, ¿no es así? Si bien cuando alguien habla de un Wiki, todo el mundo piensa en la Wikipedia, pero yo creo que uno de sus usos más importantes es dentro de las compañias, en las Intranet.

Uno de mis favoritos, por su facilidad de uso es Twiki. No sólo es Open Source, sino que además extenderlo es muy fácil (para hacer cosas como utilizar el esquema de autenticación de su compañia). ¿Qué tan efectivo es? Bueno, en mi grupo lo utlizamos para todo: Rotación de guardias, eventos de mantenimiento, documentación de errores y características obscuras de el sistema, uso de herramientas. Desde que comenzamos esa práctica, hemos visto un incremento en la productividad de el grupo ya que podemos resolver errores comunes en menos tiempo; Lo mejor es que todos colaboramos para hacer más útil la documentación y el número de reglas que hay que seguir es tán pequeña que usarlo no toma mucho tiempo.

¿Y ustedes que usan para organizar la documentación de su compañia?

Buscar en Technorati: Wiki, linux, Open Source, twiki