archivo

Archivos diarios: septiembre 23, 2010

La documentación de los proyectos es un asunto muy controvertido y en el que en la comunidad de desarrolladores hay prácticamente tantas respuestas como personas a las siguientes preguntas:

¿Tiene utilidad la documentación de un proyecto?

¿Cuál debería ser la documentación mínima exigible?

En este artículo voy a dar mi opinión siendo consciente de que probablemente gran parte de los lectores no se sienta identificado con la misma, pero como he dicho muchas veces leer o escuchar opiniones diferentes nunca está de más.

Sobre si tiene utilidad documentar un proyecto no puedo dar una respuesta absoluta. Depende. Casi prefiero un proyecto sin documentar que un proyecto con documentación deficiente, ya que el resultado es el mismo y no se habrá gastado esfuerzo en balde. Por tanto para pueda servir la documentación de un proyecto ésta debe ser de calidad. Es importante señalar que no estoy hablando de cantidad, sino de calidad, es decir, la poca o mucha que haya, que sea buena.

Cuando hablo de calidad me refiero no solo a que los modelos e información que se reflejen en los documentos estén bien hechos sino que sean acordes a la realidad de lo que posteriormente se va a implementar. Muchas veces se tiene ejecutado un análisis y un diseño y después cuando se está construyendo se toman determinadas decisiones que no han tenido reflejo en la documentación.

Lo ideal es que además cuando se hablase de calidad lo estuviéramos haciendo en el sentido de que las decisiones reflejadas en la documentación sean adecuadas, es decir, que los requisitos que se hayan tomado sean buenos, que los modelos y arquitectura representados sean coherentes, etc…, sin embargo una documentación puede ser válida aunque se hayan cometido errores en los procesos de análisis y diseño (que, por otra parte, no es solo algo probable sino algo totalmente cierto), lo importante, es que lo que contega, tal y como he comentado en el párrafo anterior sea acorde con lo que se ha hecho y si en la construcción hay que hacer cambios respecto a lo planificado que dichos cambios estén recogidos en la documentación.

Si la documentación es buena sí que puede tener utilidad (no es condición suficiente). Todos (no soy una excepción) hemos renegado de la documentación de los proyectos de desarrollo de software, sin embargo, siempre nos acordamos de ella cuando la necesitamos y no disponemos de la misma (fundamentalmente cuando nos queremos integrar con un tercer sistema o cuando adoptamos un sistema de información que se encuentra en etapas tardías del desarrollo o en mantenimiento).

Otro característica que debe tener la documentación sea útil es que sea sostenible con el futuro mantenimiento del proyecto, si no es así, gran parte de la documentación quedará desactualizada en el proceso de mantenimiento (que recordemos, según Robert Glass supone entre el 40% y el 80% del montante total del proyecto, siendo un 60% mejoras). Por tanto, no debemos pedir en los proyectos, documentación que después no podamos mantener (quedará muy bonito como histórico del proyecto e incluso puede tener una cierta utilidad para comprender los objetivos del mismo, pero al final, si se quiere entrar en detalle habrá que pelearse con el programa). Como es lógico queda fuera de esto la documentación propia de la gestión ordinaria del proyecto como por ejemplo actas de reuniones, documentación de referencia, etc… que forman parte del día a día y que no requieren actualización. También es importante señalar que la estrategia de la gestión de la configuración de la documentación debe permitir que dada una determinada versión del programa, podamos rescatar la que le corresponde a la misma (no es tan fácil como parece).

Hay que tener en cuenta también que aunque se dispongan de los medios necesarios, lo mismo la naturaleza del proyecto no requiere una documentación extensa, eso es necesario valorarlo y no invertir más dinero y esfuerzo que el que realmente se requiere (hay que tener en cuenta que buena parte de los modelos se pueden obtener por ingeniería inversa).

Si la documentación es de calidad y acorde a los medios presentes (y que se estimen futuros) del proyecto ya se va por el buen camino, pero siguen sin ser suficientes para que la documentación cumpla todo lo que debería ser su propósito, ya que no solo debe dejar rastro de lo que se ha hecho y de cómo está en la actualidad el sistema de información sino que la misma debe formar parte del proceso de desarrollo, es decir, la construcción del sistema de información no debe ser una cosa y la documentación otra, sino que lo que se construya debe ser resultado de dicha documentación.

Utilizar la estrategia de integrar la documentación de los proyectos en el proceso de desarrollo no asegura nada, ya que la ejecución final puede ser deficiente, el análisis y el diseño pueden tener errores, etc… y además se pueden construir sistemas que funcionen de manera adecuado sin haber documentación de por medio. Pese a la no existencia de garantías, yo sí creo en que el proceso de desarrollo de software es un proceso de ingeniería y que cuanto más y mejor se aplique mejores resultados se obtendrán.

Por tanto y a grandes rasgos, para que una documentación pueda ser de utilidad debe integrarse en el proceso de desarrollo, ser de calidad y acorde a las posibilidades que se prevén tengamos en el futuro mantenimiento.