República Bolivariana de Venezuela
Ministerio del Poder Popular para la Educación Superior
Universidad Nacional Experimental Simón Rodríguez
Núcleo - Valles del Tuy



Sistemas de Documentación




Facilitador:
Lic. Kristian Cedeño



Santa Teresa del Tuy; Junio de 2008

Introducción.-

El mundo de la computación ha permitido diversos avances a la humanidad, como más facilidad para tratar gran cantidad de información, más rapidez al sacar cuentas con grandes sumas, entre otras cosas.

Esas facilidades las brindas diversos programas realizados por los mismos seres humanos quienes, para poder lograr el buen uso y perdurabilidad de los mismos, deben documentarlos, permitiendo así un mejor entendimiento de los sistemas por parte de los usuarios de los mismos, así como también para los analistas y programadores.

En el presente trabajo se tratarán diversos conceptos relacionados con lo anteriormente expuesto y de gran importancia para el mundo de los sistemas basados en un computador.

UNIDAD I
Definición de Sistema.-

Un sistema es un conjunto de partes o elementos organizados y relacionados que interactúan entre sí para lograr un objetivo. Los sistemas reciben (entrada) datos, energía o materia del ambiente y proveen (salida) información, energía o materia.
Un sistema puede ser físico o concreto (una computadora, un televisor, un humano) o puede ser abstracto o conceptual (un software). Cada sistema existe dentro de otro más grande, por lo tanto un sistema puede estar formado por subsistemas y partes, y a la vez puede ser parte de un supersistema.
Los sistemas tienen límites o fronteras, que los diferencian del ambiente. Ese límite puede ser físico (el gabinete de una computadora) o conceptual. Si hay algún intercambio entre el sistema y el ambiente a través de ese límite, el sistema es abierto, de lo contrario, el sistema es cerrado. El ambiente es el medio en externo que envuelve física o conceptualmente a un sistema. El sistema tiene interacción con el ambiente, del cual recibe entradas y al cual se le devuelven salidas. El ambiente también puede ser una amenaza para el sistema.
Un grupo de elementos no constituye un sistema si no hay una relación e interacción, que de la idea de un "todo" con un propósito.

Tipos de Sistemas.-

1) En cuanto a su constitución, pueden ser físico o abstracto.
- Sistemas Físicos o Concretos: compuestos por quipos, maquinarias, objetos y cosas reales, El Hardware.
- Sistemas Abstractos: compuestos por conceptos, planes, hipótesis e ideas, muchas veces existen en el pensamiento de las personas. El Software.
2) En cuanto a su naturaleza, pueden cerrados o abiertos.
- Sistemas Cerrados: no existen sistemas cerrados, se le da el nombre del mismo a aquellos sistemas cuyo comportamiento es determinístico y programado que opera con muy pequeño intercambio de energía y materia con el ambiente.
- Sistemas Abiertos: presentan intercambio con el ambiente, a través de entradas y salidas e intercambian energía y materia con el mismo, sus estructura es óptima cuando el conjunto de elementos del sistema se organiza aproximándose a una operación adaptativa. Los sistemas abiertos no pueden vivir aislados.


Documentación.-


Ciencia que tiene como objeto de estudio el proceso informativo _ documental y desarrolla la aplicación técnica de: selección y compilación, análisis y tratamiento sistemático, almacenamiento y diseminación rápida de los registros del conocimiento humano ya sea en su forma original o interpretada; síntesis, traducción, para la obtención del nuevo conocimiento o de otra utilidad para los usuarios.

Sistemas de Documentación.-

La documentación de sistemas es el conjunto de información que nos dice qué hacen los sistemas, cómo lo hacen y para quién lo hacen.
La documentación consiste en material que explica las características técnicas y la operación de un sistema. Es esencial para proporcionar entendimiento de un sistema a quien lo vaya a usar para mantenerlo, para permitir auditoria del sistema y para enseñar a los usuarios como interactuar con el sistema y a los operandos como hacerlo funcionar.
Otra definición sería la de registro físico, generalmente por escrito que contiene los siguientes elementos:
Políticas y normas referentes al desarrollo del sistema, su implantación, operación y mantenimiento.
El diseño del sistema de información administrativo.
Procedimientos para instalar el sistema de información administrativo.Procedimientos para operar el sistema de información administrativo.Procedimientos para mantener el sistema de información administrativo.

Características que deben cumplir los Sistemas de Documentación.-

- Deben ser aprobados, firmados y fechados por las personas apropiadas y autorizadas, ningún documento puede ser cambiado sin autorización.
- El contenido de los mismos no puede ser ambiguo, el titulo, tipo y propósito deben estar establecidos claramente.
- Deben ser legibles.
- Sencillez, definir las especificaciones de todos los materiales, procesos tecnológicos, control y de las actividades relacionadas con la investigación.
- Seguridad, evitar errores.
- Eficiencia y efectividad, asegurar que todo el personal relacionado con la investigación sepa qué hacer y cuándo hacerlo.
- Los documentos deben estar donde se les necesita, usarse por lo quien los requiere sin modificaciones no autorizadas, y ser llenados veraz y oportunamente.

Importancia.-

La importancia de la documentación bien podría ser comparada con la importancia de la existencia de una Póliza de Seguro; mientras todo va bien no existe la precaución de confirmar si nuestra Póliza de Seguros está o no vigente.
La documentación adecuada y completa, de una aplicación que se desea implantar, mantener y actualizar en forma satisfactoria, es esencial en cualquier Sistema de Información, sin embargo, frecuentemente es la parte a la cual se dedica el menor tiempo y se le presta menos atención.
Siempre se debe documentar un sistema como si estuviera a punto de irse a Siberia el siguiente mes, para nunca volver. Si la documentación del sistema es incompleta el diseñador continuamente estará involucrado y no podrá moverse a otra asignación.

Ventajas.-

Un sistema bien documentado, es necesario para las nuevas personas interesadas en aprender sobre el sistema y sirve como recordatorio para aquellas que usan el sistema con poca frecuencia.
Una documentación consistente y bien conservada, nos traerá como ventaja; acortar la cantidad de horas o tiempo requerido por nuevas personas para aprender el sistema antes de realizar el mantenimiento.


UNIDAD II
Técnicas de Documentación de Sistemas.-

No hay un solo estándar de técnica de diseño y documentación actualmente en uso, a continuación se presentarán, de forma general, ciertas técnicas que están en uso. Por supuesto, cada una tiene sus ventajas y sus desventajas debido a que cada una de ellas tiene propiedades únicas.

Diagramas de Flujo
Representa la esquematización gráfica de un algoritmo, el cual muestra gráficamente los pasos o procesos a seguir para alcanzar la solución de un problema.

Ventaja:
Tal vez la mejor razón para el uso de diagramas de flujo es que han sido usados desde hace mucho tiempo y las gentes que han sido ascendidas dentro de una compañía a lo largo de los años pueden comprender mejor los diagramas de flujo sobre las nuevas técnicas.

Desventajas:
- No son trazados de acuerdo con los principios fundamentales de programación estructurada, por lo que muestran el flujo del programa pero no su estructura.
- Ocupan bastante espacio por lo que el lector debe hojear muchas paginas para entender lo que hace el programa.

Pseudocódigo
• El pseudocódigo describe un algoritmo utilizando una mezcla de frases en lenguaje común, instrucciones de programación y palabras clave que definen las estructuras básicas.
• Puede ser utilizado como un paso intermedio para el desarrollo de código de programa.
• Es apreciado naturalmente por los programadores.

Manuales de Sistemas
La documentación de sistemas es el conjunto de información que nos dice qué hacen los sistemas, cómo lo hacen y para quién lo hacen.
La documentación consiste en material que explica las características técnicas y la operación de un sistema.
Proporcionar entendimiento de un sistema a quien lo vaya a usar para mantenerlo y para enseñar a los usuarios como interactuar con el sistema y a los operandos como hacerlo funcionar.
Existen varios tipos de documentación. La de programas, que explica la lógica de un programa e incluye descripciones, diagramas de flujo, listados de programas y otros documentos; la del usuarios en forma general la naturaleza y capacidades del sistema y cómo usarlo.

Selección de una Técnica de Documentación.-

Sea compatible con la documentación existente.
Sea comprendida por los demás de la organización.
Permita que se regrese al trabajo sobre un sistema después de que se haya estado retirado de el por un tiempo.
Sea adecuada para el tamaño del sistema en que se esta trabajando.
Permita fácil modificación.


UNIDAD III
Manuales de Sistemas de Documentación.-

Los manuales del sistema juegan un papel importante en la implementación de sistemas ya que eliminan la necesidad de que el analista de sistemas se encuentre dedicado totalmente al soporte de usuarios y simplemente puede estar esperando por consultas que el usuario no pudo evacuar con la documentación que se le proporcionó.

Generalmente, en la etapa de implementación, la mayoría de consultas se refieren al uso del sistema, lo cual debe estar claramente explicado en el manual de usuario.

La documentación garantiza la continuidad del mantenimiento de las aplicaciones.

Se debe asignar un responsable de administrar la documentación, sobre todo de los sistemas generados internamente o por consultores externos, pero es importante que cada analista programador que da mantenimiento al sistema elabore y actualice, según sea el caso, la documentación pertinente siguiendo los estándares establecidos para tal fin.

Es importante que los símbolos convencionales se usen en todos los diagramas de flujo para prescribir el sistema y que en la documentación se usen formas estandarizadas.

Al estandarizar la documentación del sistema, la organización logra varias ventajas tales como:
Ayuda al entrenamiento del nuevo personal dentro y fuera de la organización de sistemas.
Es útil para cualquiera que tenga la responsabilidad del mantenimiento de los sistemas.
Ayuda a los analistas y diseñadores de sistemas en el trabajo de integración de sistemas.
Asegura que el sistema opere correctamente.
Se utilizan eficientemente los recursos que se dispongan.

Manual del Usuario.-

Expone los procesos que el usuario puede realizar con el sistema implantado.

Para lograr esto, es necesario que se detallen todas y cada una de las características que tienen los programas y la forma de acceder e introducir información.

Reúne la información, normas y documentación necesaria para que el usuario conozca y utilice adecuadamente la aplicación desarrollada.

Objetivos del Manual del Usuario
Que el usuario conozca cómo preparar los datos de entrada.
Que el usuario aprenda a obtener los resultados y los datos de salida.
Servir como manual de referencia y aprendizaje.
Definir las funciones que debe realizar el usuario.
Informar al usuario de la respuesta a cada mensaje de error.
Definir los diferentes tipos de usuarios
Definir los módulos en que cada usuario participará.

Importancia del Manual del Usuario
Los documentos a los que se puede dar entrada por computadora.
Los formatos de los documentos.
Las operaciones que utiliza de entrada y salida de los datos.
El orden del tratamiento de la computadora con los datos introducidos.
El momento en que se debe solicitar una operación deseada.
Los resultados de las operaciones realizadas a partir de los datos introducidos.

Contenido del Manual del Usuario
1. Diagrama general del sistema.
2. Diagrama particular detallado.
3. Explicación genérica de las Fases del Sistema.
4. Instalación del Sistema.
5. Iniciación al uso del Sistema.
6. Manual de Referencia.

Manual del Analista.-

El manual del analista, también conocido como Manual Técnico juega un papel importante dentro del sistema debido a que luego de instalar el sistema y ponerlo en producción, se tiene la ardua tarea de darle mantenimiento para que el sistema continúe siendo operacional.

Tomando en cuenta que las personas que dan mantenimiento al sistema no necesariamente son las mismas personas que lo desarrollaron, es necesario contar con una herramienta o el manual técnico que me permita aprender fácilmente como esta integrado el sistema desde el punto de vista técnico, presentando claramente cada uno de los procesos del sistemas y su interrelación para formar el sistema completo.

Además de indicar cada uno de los datos o información que se almacena en la base de datos del sistema, sus relaciones y las transformaciones que sufren los datos para convertirse en información.

Elementos que debe incluir el Manual del Analista
El diagrama funcional de todo el sistema.
La descripción de procesos detallando E-P-S.
Diagramas de flujo de procesos y algoritmos del sistema.
El diagrama Entidad-Relación.
Estructura de datos y características físicas y lógicas de los archivos usados.
Detalle de las condiciones especiales de ejecución tales como banderas, palabras claves, prerrequisitos, usos específicos de recursos.
Descripción de interfases con otros sistemas o aplicaciones.
Bitácora de cambios dentro de los mismos códigos fuentes que incluya el responsable del cambio, la fecha y la descripción del cambio.

Este manual debe ser actualizado constantemente inmediatamente después de hacer cualquier modificación (mantenimiento) al sistema; de tal manera que el próximo que lo consulte esté basado en una información real al momento de efectuar un nuevo cambio al sistema.

Manual de Operación.-

El Manual de Instrucciones al Operador proveerá instrucciones de cómo correr el sistema. El analista deberá trabajar en conjunto con las especificaciones funcionales, diseño del sistema y documentación de programas para escribir el Manual de Instrucciones al Operador. Este Manual deberá estar estructurado de manera tal que sirva de ayuda al adiestramiento del personal.

Contenido del Manual de Operación
El Manual de Instrucciones al Operador deberá incluir lo siguiente:

Instrucciones al Operador:


· Descripción del Programa


· Flujogramas Generales del Programa


· Parámetros


· Mensajes al Operador


· Instrucciones para etiquetas de cintas de salida (“labels”)


· Planes de Resguardo (“backups”)


· “Command Procedures”


· Instrucciones Especiales



Descripción del Programa
Incluirá descripción narrativa del programa y qué debe hacer el Operador antes y mientras ejecuta los programas del sistema.

Flujograma General del Programa
Deberá incluir copia del Flujograma General del Programa, tal como aparece en el Manual de Diseño del Sistema. Este flujograma reflejará la interrelación de programa a programa con los archivos correspondientes. Además, se indicará la frecuencia de cada programa, disposición de cada archivo, etiquetas de archivos de salida en cinta magnética, destino de cada copia de los informes y algún comentario específico de cada uno de los programas.

Parámetros para ejecutar programas
Se deberá incluir una lista de todos los parámetros para ejecutar cada programa.

Mensajes al Operador
Indicará una lista detallada de todos los mensajes, tal como aparecen en la consola, las posibles contestaciones y el por qué de dichas respuestas. Esto se hará para cada programa.

Planes de Resguardo (“backups”)
Deberá incluir instrucciones específicas de los procedimientos a seguir para el mantenimiento de un resguardo (“backup”).

Instrucciones Especiales
En esta sección se deberá incluir un itinerario de fechas para ejecutar cada programa (frecuencia), fecha de cierre, flujo de documentos, control de cintas (ciclo de retención), formas especiales de impresora y algún otro comentario que se crea pertinente.





Manual de Programación.-

El objetivo de los manuales de programación es familiarizar a analistas y programadores con lo que hace cada programa en particular.

Los manuales de programación son una extensión de la documentación del sistema. El programador convierte las especificaciones de programas en lenguaje de computador. El programador deberá trabajar conjuntamente con las especificaciones de programas y asegurarse que el programa cumpla con las mismas. Cualquier cambio que surja como resultado de la programación, deberá ser expuesto y aceptado antes de aplicar el cambio.

Estos manuales deben ser técnicos, detallados y no necesitan estar escritos en una manera entendible al usuario.

Contenido de un Manual de Programación
La documentación detallada de cada programa deberá incluir los siguientes elementos que apliquen:

· Nombre del Programa (código)

· Descripción

· Frecuencia de Procesamiento

· Fecha de Efectividad

· Archivos de Data

· Lista de Archivos de Salida

· Lista de Informes

· Datos de Prueba

· Mensajes al Operador - Pantallas (en caso que aplique)

· Datos de Control para ejecutar el programa (parámetros)

· Transacciones

· Nombre del Programador

· Fecha


Nombre del Programa
Indicará código que identifica el programa y el título del programa.

Descripción
Indicará la función que realiza el programador.

Fecha de Efectividad
Fecha a partir de la cual se comienza a ejecutar en producción la versión modificada o desarrollada del programa.

Archivo de Entrada (Librería/Definición DBD/Descripción de Archivo)

Archivos de Salida
Indicará el nombre y copia de la librería/DBD/Descripción de los archivos.

Informes y/o Totales de Control
Se indicará el nombre de los informes y se incluirá ejemplo de los informes y/o totales de control producidos por el programa, utilizando los datos de prueba.



Nombre del Programador
Deberá indicar el nombre del programador que escribió el programa o que efectuó el cambio, según sea el caso.

Fecha
Indicará fecha en que se escribió el programa o que se efectuó el cambio, según sea el caso.

Tablas
En caso que aplique, se incluirá detalle de las diferentes tablas y códigos usados; con los valores, explicaciones y su uso en el programa.

Lista de Programas
Deberá incluir copia de la última compilación del programa con todas las opciones. Cotejará que la secuencia del programa sea correcta.

Lista de Datos de Prueba
Se incluirá una copia de los datos usados para prueba.

Mensajes al Operador
En caso que aplique, deberá definir todos los mensajes al operador por consola y las posibles contestaciones con una breve explicación de cada una de ellas.

Parámetros
Se acompañará una lista detallada de todos los parámetros para ejecutar el programa (JCL, “Command Procedures”, etc.)

Manual del Diseño.-

El objetivo primordial del manual de diseño del sistema es el de proveer a los programadores suficiente información para escribir los programas de aplicaciones en lenguaje de computador.
Este manual forma parte de las especificaciones funcionales, ya que convierte la definición orientada al usuario en una definición orientada a sistemas computadorizados.

El Analista que esté desarrollando el diseño del sistema deberá trabajar conjuntamente con las especificaciones funcionales y enmendarlas, si fuera necesario.

Cualquier cambio a las especificaciones funcionales, como resultado del diseño del sistema, debe ser aprobado antes de proceder a actualizar el documento original.

El Manual del sistema deberá contener la documentación de cada uno de los programas que lo componen.

Contenido del Manual de Diseño
Introducción
Se incluirá una descripción breve de la situación que motivó la creación del sistema. Se acompañará, si aplica, la base legal que justifique dicho sistema.

Descripción General del Sistema
Deberá presentar descripción narrativa del sistema y sus funciones. Además, se incluirán todos los programas que componen el sistema y su respectiva documentación.

Flujograma
Se incluirá flujograma general del sistema, en el cual se identificarán los programas para usos, archivos e informes que componen el mismo.

Formato de Archivos, Bases de Datos y/o Bloques de Datos
Formato de Archivos, Bases de Datos a ser utilizados por el sistema, deberán ser definidos y debe incluirse una breve descripción de cada uno de ellos.
Se deberá incluir el nombre del archivo y extensión, así como la siguiente información para cada uno:
• Copia de la librería

• Definición de DBD

• Definición de los campos de aquellos archivos que no están configurados en librerías o que no están definidos en DBB (“Data Base Definition”)


Formato de Pantallas
Si el sistema es en línea, deberá incluir formato de las pantallas que serán utilizadas por el sistema.

Especificaciones de Programas
Serán establecidos en la solicitud de cambio/desarrollo de programación (UPRB-OSI-P001). Para cada programa se debe incluir lo siguiente:
a. Identificación del Programa (código)
* Descripción
* Tipo de Programa (“Batch” , en línea, etc.)
* Nombre de Archivos de Entrada
* Nombre de Archivos de Salida
* Base de Datos (cuando aplique)
* Nombre de Informes

b. Descripción del Programa (UPRB-OSI-P005)
Narrativa de las funciones del programa. Se incluirá la definición de lo que hace el programa. Deberá ser lo más clara, organizada y precisa posible, además de estar bien presentada.

c. Formato de Pantallas
Si el sistema es en línea, deberá incluir formato de las pantallas utilizadas por el programa.

d. Formato de Archivos de Entrada y/o Salida (librería, DBD o definición) y Definición de la Base de Datos (cuando aplique).

e. Formato de Informes
Se incluirán formatos de los informes que producirá el programa.