Documentar, documentar, documentar!!!

documentar

En el proyecto en el que estoy trabajando ahora mismo entramos en una fase de “traspaso de conocimiento al cliente“, en el que debemos entregar a los informáticos del cliente toda la documentación de los proyectos en los que hemos trabajado en los últimos 3 años.

Al principio recibí esta noticia sin ningún sobresalto. Sólo tendría que recopilar del gestor documental para cada aplicativo, el análisis previo realizado para la toma de requisitos con su correspondiente análisis funcional, la documentación de la base de datos, el manual de usuario y verificando que toda esta documentación estuviese al día y sumado a un código bien comentado tendría esta entrega preparada en, como mucho, un par de días, pero…

¿Existía toda esta documentación en el gestor documental?

Pues como muchos intuiréis, NO. Resulta que, a pesar de que los módulos y aplicaciones de los que me he encargado yo si tenían toda la documentación mencionada, para la mayoría de los módulos y aplicativos existía, como mucho, uno o dos de los documentos que yo esperaba encontrar, y es que por lo general no nos gusta documentar, pero eso no es excusa para hacerlo.

Con este artículo tengo la intención de concienciar un poco a la gente para que trate de mantener una documentación mínima de los desarrollos en los que trabaja que, a pesar de ser una tarea aburrida y engorrosa, es también una parte importante de nuestro trabajo.

He oído muchísimas excusas para evitar documentar: La mejor documentación es el código fuente, el manifiesto ágil afirma que se valora más el software que funcione que la documentación exhaustiva, es una pérdida de tiempo, no se lo va a leer nadie…

Ninguna de las excusas para mi es suficiente. Soy un firme defensor de las metodologías ágiles y creo que es una mala interpretación de las mismas el hecho de descartar la documentación de los aplicativos ya que una cosa es que se valore mas el software que funcione y otra muy diferente es que no sea necesaria.

Para seguir con el ejemplo que estoy viviendo ahora mismo, en un proyecto con una complejidad media ahora mismo tenemos problemas para realizar la documentación de lo que no estaba documentado ya que las cosas que parecieron obvias en el momento de desarrollarlas ahora parece que carezcan de sentido y para las que parece que tienen sentido, desconocemos en qué reglas de negocio se basó su desarrollo. Ésto termina traduciéndose en que el propio programador que hizo un módulo hace 3 años, en el principio del proyecto, ya no sabe ni porqué hizo las cosas qué hizo ni cómo las hizo, entonces yo pregunto ¿Si tu no sabes cómo va, cómo pretendes que otra persona retome tu desarrollo?

En cuanto a qué nivel de documentación llegar no creo que exista un nivel óptimo y pienso que en cada proyecto es la propia experiencia la que define hasta donde debe cubrir la documentación, pero desde mi experiencia si he visto que normalmente se puede cubrir la documentación con 4 puntos mínimos:

  • Toma de requisitos: El primer punto que es necesario para documentar un aplicativo es saber qué se espera de éste. Ésta no será una tarea muy compleja si simplemente tomamos nota de qué es lo que quiere el usuario.
  • Análisis funcional: También debemos reflejar cómo resolverá el aplicativo las especificaciones  del cliente. Sólo será necesario apuntar en un documento de forma organizada qué será lo que se desarrollará para cada requisito.
  • Definición Técnica: En este documento especificaremos la tecnología utilizada, arquitectura, etc. En otras palabras lo básico para que un programador sea capaz de comprender cómo está montado el proyecto.
  • Documentación en el código: No creo que tenga que explicar mucho en este punto, pero todos sabemos que como mínimo debemos comentar las cabeceras de las clases, procedimientos y funciones, así como el código que no se explique sólo.

Podemos apreciar que ninguno de los puntos descritos supone un gran esfuerzo para mantener una documentación mínima ya que en la mayoría de ellos lo único que debemos hacer es reflejar por escrito  lo que estamos haciendo ya sea en un correo electrónico, un gestor documental o incluso un conjunto de notas tomadas en servilletas.

Por supuesto estos 4 puntos no son obligatorios, ni constituyen una metodología, ni nada por el estilo. Es simplemente un ejemplo de una forma de cubrir la documentación y que en particular en los casos con los que me he encontrado ha funcionado.

En conclusión, una documentación mínima no supone un gran esfuerzo si se realiza a medida que vamos desarrollando y evitará, en el mejor de los casos, que un nuevo compañero se encuentre completamente perdido y, en el peor de los casos, que seamos nosotros mismos los que nos perdamos.