Desenredar los cables

Cuando has trabajado en varios proyectos de desarrollo de software de mediano-gran tamaño te das cuenta que la tendencia normal es que no exista documentación que te guíe por el código, los compañeros te ayudan pero como mejor saben (y cada uno a su manera), etc.. Esto hace que cuando se le pide a un programador que implemente sus primeras tareas este tenga la sensación de tener que "desenredar los cables" para poder empezar.

Al analizar esta situación en detenimiento, todo esto se traduce en muchos factores no deseados:

• Insatisfacción y frustración del programador.
• Costes de aprendizaje que se multiplican.
• Sensación de mala estructura del proyecto.

Siempre se debe tener un mecanismo de formación "automático" (quiero decir que no necesite de una tercera persona, es decir se le puede decir al miembro del equipo "toma esto" y con lo que se le de entonces puede formarse) para que un miembro del equipo pueda consultarlo y pueda usarlo como guia.

El procedimiento para tener un mecanismo de formación automático es tener una documentación técnica apropiada. Esta documentación tiene que tener las siguientes características:

• Estar escrita en un idioma de programadores. Lo cual garantiza que no se "hace larga de leer" y va directa al grano.
• Estar escrita en un formato cómodo de leer para un programador. Recomiendo una pagina web antes que un documento de texto.
• Que sea facil de mantener. Importante. Se debe mantener y que sea facil hacerlo ya que si no es facil de mantener entonces se abandonara.