Maestrantes:Gladys María Rodríguez

Domingo Florentino MuñozMargarita Cepeda Gómez

Bonao, julio 2012

Documentación de Sistemas

Documentación de SistemasLa elaboración de la documentación es un proceso esencial para poder garantizar la calidad del software, lo cual requiere una adecuada asignación de recursos financieros, materiales, humanos y de tiempo, o sea, la calidad del proceso de elaboración de la documentación se traduce en calidad del software. De la efectividad de la documentación depende en gran medida el éxito de los proyectos de sistemas o productos de software.

Documentación de SistemasLa Documentación de Sistema consiste en un conjunto de información relacionada a un sistema determinado que explica las características técnicas, la funcionabilidad del sistema, la parte lógica, los diagramas de flujos, los programas, la naturaleza, capacidades del sistema y cómo usarlo, en otras palabras.

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?

En la mayoría de los sistemas, la documentación siempre es expresada en un carácter técnico por excelencia, indicando algoritmos de cómo realizar alguna acción, registrar transacciones, imprimir reportes; dependiendo de la naturaleza del sistema o su función.

Es necesario indicar que muchas veces no se le da el protagonismo que se merece, puesto que en la mayoría de los casos esta documentación es muy escasa o nula, debido  a la  construcción y modificación de los sistemas de forma acelerada, consecuencias de la dinámica empresarial o quizás, el problema se encuentre del lado de los desarrolladores, programadores y administradores del proyecto de sistema, ya que como parte equipo de proyecto conocen a fondo el sistema y obvian a los futuros operadores y/o administradores del sistema.

Características de 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 título, 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 quien

los requiere sin modificaciones no autorizadas, y ser llenados veraz y oportunamente.

Tipos de Documentación

La documentación puede ser Manual y Automática.

Documentación Manual: este tipo de documentación se efectúa manualmente. Puede documentarse en papel o en algún medio magnético como CD. Se puede contar con el apoyo de software para su confección, como un procesador de texto, planilla electrónica y programas graficadores. 

Documentación Manual VentajasRefleja historia.Muestra la evolución de la documentación en el

tiempo.Más explicativa.Se adecúa a la cultura de la organización.No consume capacidad de procesamiento. DesventajasConsume mucho esfuerzo en construirla.Documentación incompleta.Poca disposición para entregar información.Más lenta y sin actualizar.Errores de escritura 

Documentación Automática: en este tipo de documentación, existen software que documentan. Pero estos software no están disponibles para todas las plataformas, por lo que hay que revisar bien el ambiente en que se trabaja para ver si existe algún software de documentación compatible. Este tipo de documentación es muy útil para: Definir el plazo y costo de trabajos de

mantención de software. Su utilización requiere de que el software a analizar haya sido desarrollado en base a alguna norma y, que esta norma haya sido respetada.

Apoyar labores de auditoría y control. 

VentajasEs inmediata y está siempre actualizada. Justo a lo requerido.No se encuentra sujeta a la disposición del personal.

DesventajasConsume recursos de Hardware.No siempre disponible, pues no hay disponibilidad

para todas las plataformas.No es explicativa

Documentación Automática

Funciones de la documentaciónLa documentación, como concepto generalizado, representa el conjunto de documentos recogidos

para fines determinados.La selección: de documentos a partir de conocimientos lo

más completo posible de cuanto existe, se está haciendo o va a producirse. Recoge, principalmente, documentos de tipo visual, auditivo o audiovisual.

La identificación: de los documentos consiste en la aplicación de reglas de escritura y presentación gráficas, simples, normalizadas y unívocas con el fin de asegurar una mejor comunicación.

El análisis documental: es un conjunto de operaciones realizadas para representar el contenido de un documento de forma distinta al original, con el fin de facilitar la consulta o la búsqueda en una etapa posterior.

El almacenamiento: es la acumulación de documen tos originales o reproducidos, introducidos en la memoria documental de modo que permitan las operaciones de recuperación y búsqueda funda mentales para localización del contenido informativo.

La difusión: de los documentos o de la información recogida, tratada y analizada. Tiene en cuenta el ejercicio de las técnicas de comu nicación entre personas presentes o ausentes en tiempo y espacio.

Importancia de la Documentación de SistemasLa documentación de un sistema es esencial para proporcionar entendimiento de quien lo vaya a usar para mantenerlo, para permitir auditorías del mismo, para enseñar a los usuarios como interactuar con él y a los operadores y administradores como hacerlo funcionar.

La documentación tiene una gran importancia dentro de una empresa, ya que esta ayuda a eliminar la posible dependencia que se pueda formar entre el proyecto realizado, y el ejecutor de éste. Para que toda aplicación tecnológica y todo servicio informático quede adecuadamente documentado, es necesario exigirle a quien lo diseñe y/o desarrolle (puede ser personal interno o un proveedor) que entregue dicha documentación obtenida a través del desarrollo del proyecto, de manera que otras personas relacionadas o autorizadas por la empresa accedan a los conocimientos necesarios para corregir errores, hacer ajustes, etc.

La oposición que entregan los técnicos a la realización del proceso de documentación, se basa principalmente en los costos en que se incurre para su construcción y en el mayor plazo de entrega. Pero estas justificaciones no son posibles de sustentar en la realidad, ya que el mayor costo en que se incurre para documentar se recupera con creces en el futuro, especialmente cuando se ve enfrentado a un error del sistema o tener que efectuarle mantenimientos correctivos por mal uso.

Estándares Básicos de DocumentaciónToda documentación que se relacione con un sistema, ya sea manual o por computadora, sencillo o complejo debe reunir los siguientes requisitos básicos:

Debe ser rotulada con claridad y bien organizada, con secciones claramente indicadas, estructuradas en carpetas e incluir un índice.

Los diagramas deberán ser claros, no aglomerados y la escritura manuscrita deberá ser legible.

Se incluirá una leyenda o explicación de los términos utilizados.

La documentación siempre se conserva actualizada.La documentación deberá ser completa.

NormalizaciónEs una actividad mediante la cual se aplican criterios preestablecidos a la realización de una actividad, aún cuando las normas de documentación varían de una instalación a otra, es esencial que dentro de una organización, se utilice un solo método.

El uso de procedimientos y documentación estandarizada proporciona la base de una comunicación clara y rápida,  adiestramiento  menos costoso del personal de sistemas, reducción de costos de almacenamiento

Para evitar confusiones en las revisiones de la documentación, se desarrollan diferentes tipos de documentos dirigidos a las personas que trabajarán con el sistema para facilitar el mantenimiento del mismo. La documentación de un sistema debe ser marcada adecuadamente, bien organizada actualizada y completa; todos los términos utilizados deben explicarse. La documentación se hará disponible a todos los usuarios de acuerdo a sus necesidades. de referencia.

El estilo de redacción de los manuales de documentación debe ser:

Concreto.Utilizar párrafos cortos.Utilizar títulos y subtítulos.Utilizar formas activas en lugar de pasivas.No emplear frases largas que presenten hechos

distintos.Preciso, definiendo los términos utilizados (añadir

un glosario).No hacer referencia a una información solamente

con el número.

La documentación básica necesaria de un sistema de información deberá contar con:

Modelos de formularios utilizados para documentar los sistemas de información:

Hoja de diseño de archivos o registrosÍndice de archivosHoja de diagramación Hoja de diseño de salidas impresas y/o

formulariosHoja de diseño de formatos de pantallaHoja de programaciónÍndice de programasTabla de decisiones y/o alternativasHoja de especificaciones del programa

Carpeta de papeles de trabajo (análisis):

Síntesis del documento de generación Presupuesto o plan de fijación de tareas Documentación del relevamiento detallado Formularios o comprobantes analizados Papeles de trabajo del análisis Estudio de factibilidad y diagnóstico

Carpeta de sistemas (diseño global):Fijación de los objetivos del sistema Descripción global del sistema Modelo lógico del sistema (DFD, diccionario de datos,

especificación de la lógica) Diseño de entradas y salidas Normas y procedimientos para los usuarios (en

operaciones de rutina, de respaldo, de emergencia, de recupero, de uso de back-up)

Recursos materiales y humanos necesarios Estudio técnico-económico acerca de la posibilidad de

procesar el sistema mediante el uso de un computador

Carpeta de programas (diseño detallado):

Descripción detallista del programa Diagrama de lógica Descripción de entradas Descripción de salidas Descripción de archivos Tablas, cuadros de control de consistencia y

parámetros utilizados Controles del programa sobre archivos y

datos

Carpeta de operaciones:Normas de control de entradas, salidas y de

procesamientos .Normas de operación, de recupero, de back-

up, de seguridad de archivos. Cronograma de procesos.Descripción de usuarios.

Herramientas

TécnicaUsuarios finalesHelp Workshop

Gracias