DOCUMENTACIÓN DURANTE EL DESARROLLO DEL SOFTWARE

Todo lo concerniente a la documentación del propio desarrollo del software y de la gestión del proyecto, pasando por modelaciones (UML),diagramas de casos de uso, pruebas, manuales de usuario, manuales técnicos, etc; todo con el propósito de eventuales correcciones, usabilidad, mantenimiento futuro y ampliaciones al sistema.



Dos estrategias de desarrollo: Ciclo de vida Estructurado y Orientación a Objetos.

Documentación y Desarrollo de Software

En general se habla mucho de la documentación, pero no se la hace, no se le asigna presupuesto, no se la mantiene y casi nunca está al día en los proyectos de desarrollo de software.

Lo importante es la disponibilidad de la documentación que se necesita en el momento en que se la necesita. 

Muchas veces se hace porque hay que hacerla y se escribe, con pocas ganas, largos textos, a la vez que se está convencido de estar haciendo un trabajo inútil. A veces se peca por exceso y otras por defecto. Ocurre mucho en la Web y con productos RAD. En ocasiones se olvida que el mantenimiento también debe llegar a la documentación.

La documentación se suele clasificar en función de las personas o grupos a los cuales está dirigida:

· Documentación para los desarrolladores

· Documentación para los usuarios

· Documentación para los administradores o soporte técnico

La documentación para desarrolladores es aquélla que se utiliza para el propio desarrollo del producto y, sobre todo, para su mantenimiento futuro. Se documenta para comunicar estructura y comportamiento del sistema o de sus partes, para visualizar y controlar la arquitectura del sistema, para comprender mejor el mismo y para controlar el riesgo, entre otras cosas. Obviamente, cuanto más complejo es el sistema, más importante es la documentación.

En este sentido, todas las fases de un desarrollo deben documentarse: requerimientos, análisis, diseño, programación, pruebas, etc.. Una herramienta muy útil en este sentido es una notación estándar de modelado, de modo que mediante ciertos diagramas se puedan comunicar ideas entre grupos de trabajo.

Hay decenas de notaciones, tanto estructuradas como orientadas a objetos. Un caso particular es el de UML, que analizamos en otra obra. De todas maneras, los diagramas son muy útiles, pero siempre y cuando se mantengan actualizados, por lo que más vale calidad que cantidad. La documentación para desarrolladores a menudo es llamada modelo, pues es una simplificación de la realidad para comprender mejor el sistema como un todo. Otro aspecto a tener en cuenta cuando se documenta o modela, es el del nivel de detalle.

Así como cuando construimos planos de un edificio podemos hacer planos generales, de arquitectura, de instalaciones y demás, también al documentar el software debemos cuidar el nivel de detalle y hacer diagramas diferentes en función del usuario de la documentación, concentrándonos en un aspecto a la vez.

De toda la documentación para los desarrolladores, nos interesa especialmente en esta obra aquella que se utiliza para documentar la programación, y en particular hemos analizado la que se usa para documentar desarrollos orientados a objetos en el capítulo respectivo. La documentación para usuarios es todo aquello que necesita el usuario para la instalación, aprendizaje y uso del producto. Puede consistir en guías de instalación

       - usuario
       - manuales de referencia
       - guías de mensajes

En el caso de los usuarios que son programadores, verbigracia los clientes de nuestras clases, esta documentación se debe acompañar con ejemplos de uso recomendados o de muestra y una reseña de efectos no evidentes de las bibliotecas.

Más allá de todo esto, debemos tener en cuenta que la estadística demuestra que los usuarios no leen los manuales a menos que nos les quede otra opción. Las razones pueden ser varias, pero un análisis de la realidad muestra que se recurre a los manuales solamente cuando se produce un error o se desconoce cómo lograr algo muy puntual, y recién cuando la ayuda en línea no satisface las necesidades del usuario. Por lo tanto, si bien es cierto que debemos realizar manuales, la existencia de un buen manual nunca nos libera de hacer un producto amigable para el usuario, que incluso contenga ayuda en línea. Es incluso deseable proveer un software tutorial que guíe al usuario en el uso del sistema, con apoyo multimedial, y que puede llegar a ser un curso online.

Buena parte de la documentación para los usuarios puede empezar a generarse desde que comienza el estudio de requisitos del sistema. Esto está bastante en consonancia con las ideas de extreme programming y con metodologías basadas en casos de uso.

La documentación para administradores o soporte técnico, a veces llamada manual de operaciones, contiene toda la información sobre el sistema terminado que no hace al uso por un usuario final. Es necesario que tenga una descripción de los errores posibles del sistema, así como los procedimientos de recuperación. Como esto no es algo estático, pues la aparición de nuevos errores, problemas de compatibilidad y demás nunca se puede descartar, en general el manual de operaciones es un documento que va engrosándose con el tiempo.


- Diagrama de contexto:

- Glosario:

Es una descripción de términos que hacen al negocio, cuya comprensión es necesaria por parte 

de diseñadores y programadores, y tiene la forma de un diccionario, poniendo los términos y sus significados. Esto a veces no es necesario, ya sea porque los términos son lo suficientemente corrientes o porque ya hubieran sido explicados en otros documentos.

- Diagrama de Gantt del proyecto: (en el proyect)

Debe hacerse el plan de trabajo del proyecto en forma de Diagrama de Gantt o similar, que luego 

se irá actualizando al final de cada etapa.

- Modelo de comportamiento:

Define el comportamiento del sistema para manejarse con éxito en el ambiente. 

Ese comportamiento se establece tomando como unidad cada una de los estímulos de la Lista de Eventos ya comentada.

- Diagrama de Entidad – Relación

Describe la distribución de datos en un sistema. Es fundamental en sistemas centrados en datos. No es necesario si el sistema tiene poco o ningún acceso a bases de datos, como algunos sitios web.

- Modelo del procesador:

Es lo que permite pasar del modelo de análisis a los distintos componentes de hardware, con sus comunicaciones. Habrá que incluir un diagrama de hardware, en el cual se muestre el hardware sobre el que se implementará el sistema, y una justificación de la elección del entorno tecnológico, en la cual se explican las consideraciones que se hicieron para elegir dicho hardware.

- Modelo de implantación de programas

Organización jerárquica de módulos en una tarea. Se realiza con un Diagrama estructurado.A continuación hay un diagrama estructurado de ejemplo:

- Diagrama de Flujo de Datos (DFD):

Es un diagrama que muestra los procesos y los flujos de datos entre los mismos. Se lo llama también diagrama de burbujas. Es fundamental cuando las funciones o procesos son más importantes que los datos.

- Interfaces de usuario

Se especifican con prototipos de las interfaces de usuario y reportes. Éstas pueden consistir en dibujos o bocetos que muestren cómo van a ser las interfaces, aun cuando luego estos sean modificados luego.

- Esquema de la Base de Datos

A continuación se muestra uno: