Documentación de PROGRAMAS: GUÍA COMPLETA y FÁCIL

Generalmente, un programa es parte de un proyecto mucho más grande, al cual normalmente se le conoce como sistema de información, o simplemente sistema.

Aunque es esencial la creación de diagramas de flujo para la planeación de un sistema o programa, solo es parte de la documentación que se requiere en una compañía. En cada compañía existen estándares propios para la documentación y las formas que se emplean varían hasta cierto punto de una compañía a otra. No importa cual sea el formato, el concepto fundamental es el deseo de comunicar información acerca de un programa o de todo un sistema en la forma mas completa y
eficiente posible.

Dentro de una organización los programadores y analistas de sistemas cambian de puesto o lo abandonan, pero los proyectos en que trabajan permanecen como parte del sistema de procesamiento de datos de la compañía. Conforme se realizan modificaciones dentro de la compañía, estos sistemas y programas requieren revisión. Si el programa o sistema no se ha documentado, entonces las modificaciones necesitaran una cantidad excesiva de tiempo. Este tiempo extra se necesita para
localizar y seguir todos los detalles del proyecto.

Dentro de la documentación básica de un sistema o programa, se deben elaborar tres tipos de manuales:

a) Manual del sistema. Dirigido al líder del proyecto de sistematización.
b) Manual del programa. Dirigido al programador.
c) Manual del usuario. Dirigido, como su nombre lo indica, al usuario final.

13.1.- Manual del Sistema.

El manual de un sistema siempre se desarrolla, mucho antes que los manuales de los programas, dado que para el desarrollo u optimización de un sistema, se requiere un trabajo previo llamado Análisis y Diseño del Sistema. Dicho trabajo normalmente es realizado por los llamados, propiamente, analistas de sistemas; quienes desarrollan el o los manuales del sistema y de los programas.

De tal manera que se utilizan los manuales del sistema como apoyo y los manuales de programas para entregarlos a los programadores como cuadernos de carga, en los cuales se describen detalladamente los programas que se deberán desarrollar.

Invariablemente los manuales de los programas, también llamados cuadernos de carga, serán complementados con información que anexará el programador.

Dependiendo de la técnica de análisis utilizada, se tendrá la estructura del o los manuales del sistema. Una de estás técnicas, por ejemplo, incluye lo que serían tres capitulos dentro del manual del sistema, como son:

1. Análisis Previo.
2. Análisis Funcional.
3. Análisis Orgánico.

Sin embargo, el Análisis y Diseño de Sistemas, será otra materia interesante y digna de estudio por parte del lector.

13.2. - Manual del programa.

Los elementos más comunes de documentación son:

1. Nombres de los archivos de datos, y los programas que los usan.
2. Descripción de los registros de los archivos de datos.
3. Tablas de impresión.
4. Narrativa del programa.
5. Hoja de corrida.

Cuando un programa se ha completado (escrito y probado), se separa un paquete de documentación. Se preparan versiones finales de los elementos antes mencionados y se agregan los que siguen:

1. Una tabla del contenido del paquete de documentación.
2. Diagrama de flujo.
3. Un listado de programa fuente (listado del programa, según lo codifico el programador, producido por la "máquina"). Esta es la versión final del programa fuente después de que se han corregido todos los errores y el programa ha producido la salida correcta.
4. Muestras de los informes impresos producidos por el programa y, en particular, cualesquiera formas especiales previamente impresas que puedan utilizarse al producir la salida.
5. Un diagrama de flujo del sistema puede incluirse para mostrar a que parte del sistema corresponde este programa.

13.3. - Manual del usuario.

En este caso se desarrolla un manual explicando el funcionamiento del programa, y como deberá usarlo el usuario. Las explicaciones deberán ser claras y sencillas, de tal manera que sea fácil de entender, inclusive por cualquier persona que no tenga un gran conocimiento de computación, o definitivamente desconozca el manejo de un equipo de computo.

Los manuales individuales de los programas, se integraran en un único manual del usuario, es decir, el manual del sistema.

Este manual del usuario o guía del usuario, como le llaman algunos, debe tratar de por lo menos algunos de los siguientes puntos:

· Prefacio.
Con una explicación general del objetivo del sistema o programa, sus requerimientos de hardware y software, así como las convenciones establecidas en cuanto a los tipos de letra utilizados en el manual para hacerlo más explicito.

Por ejemplo, en un manual se podría establecer lo siguiente para el usuario:
Convención Significado
-Negrita En los procedimientos, indica el texto que usted escribe.
-Cursiva Indica un término del glosario.

Así mismo, deberá contener información acerca del lugar o persona de contacto para obtener soporte técnico.

· Introducción (o bienvenida).

Con una breve descripción acerca de las facilidades del programa o sistema, o bien, de las innovaciones, si es que es una versión actualizada.

· Capitulos de las opciones (uno para cada opción principal del programa).

Por lo menos se deberá dedicar un capitulo a cada una de las principales opciones del programa o sistema. Dichos capítulos y el número de éstos se desarrollarán a criterio del equipo de trabajo que desarrolla los manuales del sistema o programa.

· Apéndices (si son necesarios).

Que contendrán información adicional acerca de temas o información indirectamente relacionados al programa o sistema.

· Glosario.

Con definiciones de términos técnicos y conceptos.

· Índice (temático o alfabético).

Obviamente con los números de página en donde se encuentra la información que requiera el usuario.