La documentación se integra de todos los elementos que explican las características de un programa o sistema, y son necesarios para poder utilizarlo, operarlo o modificarlo.
Documentar es una tarea tan necesaria e importante como escribir el código: el código indica cómo funciona el programa, y la documentación indica porqué lo hace.
El responsable de un proyecto no debe permitir que se entreguen sistemas sin documentación. Cuando un programa es pequeño el programador generalmente puede retener en la mente todos los detalles (al menos por algún tiempo), por lo cual no necesita de documentación. En el caso de programas amplios se vuelve imposible recordar cómo se relaciona cada detalle con los demás.
Si además se considera que posteriormente el programa tendrá que ser modificado, se apreciará que el propósito del código de un programador no es solamente instruir a un dispositivo electrónico sobre cómo solucionar un problema, sino informar a los futuros programadores sobre cómo fue resuelto el problema.
Pero la documentación no sólo es para los programadores, también los usuarios de los programas necesitan de ayuda para operarlo; e incluso el comprador requiere de material que le permita evaluarla compra.
Hacer que la documentación sea concisa y descriptiva a la vez. Ser congruente en todos los programas.
El tiempo de lectura de los programas es mucho más largo que el de escritura.
Si el proyecto es pequeño, puede ser suficiente con recopilar toda la documentación en un archivo e integrarlo con los demás archivos del programa.
MANUAL TECNICO O DE MANTENIMIENTO: Documentación destinada a los programadores y sirve de referencia para darle mantenimiento a un sistema durante su vida útil. Tiene dos niveles: Interna y Externa. Documentación interna: Son los comentarios que se encuentran dentro del programa fuente, y que describen detalles significativas para un programador.
Documentación externa: Es aquella que se encuentra independiente del programa fuente. Suele encontrarse en un manual (impreso) que se proporciona con el programa y describe con profundidad sus características técnicas y funcionamiento.
Manual del usuario: Es un documento que le indica al usuario (u operador) conocer, utilizar y operar correctamente el sistema. Describe los objetivos y opciones del programa, así como sus características externas. La documentación básica para un programa (o un sistema pequeño) se muestra en el cuadro 5-1. Sin embargo, si se desarrolla un sistema grande o complejo, cada etapa del proceso de desarrollo deberá ser documentada. A continuación mencionamos algunos de los puntos que conviene incluir, pero sin profundizar en ellos. Gracias a Noelia Emilia Fernández por colaborarnos este artículo para ser publicado en ARQHYS.com…
