Guía para la redacción y evaluación de la documentación del sistema

República Bolivariana de Venezuela

Ministerio del Poder Popular para la Educación Universitaria, Ciencia y Tecnología

Universidad Politécnica Territorial del Estado Mérida “Kleber Ramírez”

Programa Nacional de Formación en Informática

Sede Ejido - Estado Mérida.

GUÍA PARA LA REDACCIÓN Y EVALUACIÓN DE LA DOCUMENTACIÓN DEL SISTEMA

Propuesta en Revisión

Elaborado por.

• Profesor Vladimir Moncada.

Ejido, Estado Mérida mayo 2025.

INTRODUCCIÓN

      El quehacer de los y las estudiantes universitarios en las diferentes disciplinas, está caracterizado por el trabajo investigativo como un mecanismo para conocer y proponer soluciones ante las necesidades o problemas de las organizaciones.

   En el sentido de lo anteriormente expresado, esta guía tiene por finalidad contribuir con los procesos de redacción y presentación de la  documentación del sistema, que debe desarrollar  los alumnos de la Universidad Politécnica Territorial del Estado Mérida como parte de su proceso formativo, y por esta razón, se enfoca básicamente en la facilitación de lineamientos para apoyar esta actividad.

Diagramas HIPO

   El diagrama Hipo (En inglés, Hierarchy-Input-Process-Output) es una descripción gráfica del sistema y permite entre otras cosas:

1. Especificar cuáles son las entradas y salidas de un proceso.
2. Representa la jerarquía de los módulos en el sistema de Software.
3. En la documentación facilita entender de forma visual la estructura del sistema que se está desarrollando.

La metodología de documentación HIPO (Hierarchy plus Input-Process-Output) utiliza varios tipos de diagramas para describir un sistema. Los principales son:

• Diagrama de la Tabla Visual de Contenido (VTOC - Visual Table Of Contents): Este diagrama representa la estructura jerárquica del sistema. Actúa como un mapa que permite localizar los diferentes módulos o componentes dentro de la organización del programa. Es similar a un organigrama.
• Diagramas IPO (Input/Process/Output): Estos diagramas se centran en la funcionalidad de cada módulo identificado en el VTOC. Pueden representarse con diferentes niveles de detalle:

• Diagramas IPO Generales: Ofrecen una visión de alto nivel de un módulo, mostrando de forma concisa las entradas principales, el proceso principal que se realiza y las salidas principales que se generan. Son útiles para una comprensión inicial y para comunicar la función general del módulo.
• Diagramas IPO Detallados: Proporcionan una visión en profundidad, desglosando con mayor especificidad las entradas, los pasos o sub-procesos dentro del proceso, y las salidas. Se generan a partir de los diagramas IPO generales y son útiles para el análisis técnico, el diseño y la implementación.

En la documentación HIPO, es común incluir al menos el diagrama VTOC para mostrar la estructura del sistema, complementado con diagramas IPO (ya sean generales o detallados, según la necesidad) para describir la función de cada módulo.

Para la documentación del sistema se sugiere indicar como mínimo  el VTOC, ejemplo:

[pic 1]

Figura. 1. Aspectos a considerar en la redacción de los diagramas Hipo - Vtoc

Fuente: elaborado por el autor, tomando como referente los esquemas para la redacción de proyectos socio tecnológicos, propuestos por Alviarez (s.f.), y Dugarte y Gonzales (s.f.)

Lineamientos Básicos Para VTOC

 Son esquemas de representación para un desarrollo jerárquico de arriba hacia abajo.

 El diagrama debe corresponderse con los módulos que efectivamente tiene el sistema desarrollado.

 La estructura mostrada en el diagrama debe corresponderse (en orden y contenido) con la estructura que efectivamente tiene el sistema desarrollado.

  Se recomienda comentar el diagrama.

Lineamientos Adicionales Para VTOC

  Consistencia en la Notación: Definir y utilizar una notación visual consistente para representar los módulos y las relaciones jerárquicas. Esto facilita la lectura e interpretación del diagrama. Por ejemplo, usar rectángulos para los módulos y líneas para indicar la relación padre-hijo.

  Identificación Única de Módulos: Asignar un identificador único a cada módulo dentro del VTOC. Esto facilita la referencia a módulos específicos en la documentación o durante las discusiones. Estos identificadores podrían ser números o códigos alfanuméricos.

  Claridad en los Niveles de Jerarquía: Asegurarse de que los diferentes niveles de la jerarquía sean visualmente distintos y fáciles de identificar. Esto ayuda a comprender la profundidad y la organización del sistema.

  Propósito Breve de Cada Módulo: Incluir una breve descripción del propósito o la función principal de cada módulo directamente en el diagrama (o referenciada a través del identificador único). Esto enriquece la información visual y reduce la necesidad de consultar documentación externa para una comprensión general.

  Revisión y Actualización: Establecer un proceso para revisar y actualizar el VTOC a medida que el sistema evoluciona. Un VTOC desactualizado pierde su valor.

  Orientación y Flujo Lógico: Diseñar el diagrama de manera que el flujo jerárquico sea intuitivo de seguir (generalmente de arriba hacia abajo o de izquierda a derecha).

  Considerar el Nivel de Detalle: Definir el nivel de detalle apropiado para el VTOC según su propósito y la audiencia. Un VTOC para una visión general podría tener menos detalles que uno utilizado para la documentación interna del equipo de desarrollo.

Modelos VTOC ADICIONALES

MODELO 1

[pic 2]

Figura 2. Modelo de Vtoc.

MODELO 2

[pic 3]

[pic 4]

Diagrama de Flujo de Datos (DFD)

   Este tipo de diagrama representa tanto el flujo o camino recorrido por los datos, como los procesos a que son sometidos dichos flujos, para producir las salidas esperadas. Los DFD deben exhibir las siguientes características:

1. Deben existir flujos de entrada (datos de entrada).
2. Deben existir productos o salidas.
3. Deben existir entidades que proporcionan el flujo de entrada, y/o reciben los flujos de salida o productos.
4. Estas entidades deben se externas, es decir no pertenecen al sistema que se está representando.
5. Deben existir procesos que transforman a las entradas en salidas.
6. Debe existir una ruta o camino que lleve los datos de entrada a los procesos.
7. Debe existir una ruta o camino que lleve los datos de salida de un proceso, a otro proceso que los recibe como entrada.
8. Deben existir almacenes de datos, que representan lugares donde se guardan los datos de forma persistente, con flujos de datos que entran y salen de ellos.

   Para la elaboración de los DFD, no existe una simbología única, ya que autores de prestigio como Kendall y Kendall, Yourdon, Gane y Sarson, han desarrollado sus respectivas propuestas.

A continuación se muestra las simbologías propuesta por Yourdon y Gane & Sarson:

Tabla 2. Símbolos para la elaboración de diagramas de flujo de datos.

Fuente: Kendal y Kendall (2005).

...