Organización general para la documentación de Sistemas

La descripción de la solución adoptada para la realización de un sistema propuesto puede hacerse de formas muy variadas.
La finalidad de este documento es proponer una forma simple de abordar ese problema para que sea usada en la presentación de prácticas de laboratorio en las que se exija la implementación de una solución completa. Estas normas deberán entenderse como un mínimo orientativo en la organización de dicha documentación.
La documentación de un sistema deberá dividirse en las siguientes partes :
• Documentación de construcción.
• Índice de contenido.
• Especificación.
• Arquitectura.
• Módulos de nivel 1.
• Módulos de nivel 2.
• Módulos de nivel n.
• Documentación de uso.
• Manual del usuario.
• Configuración del sistema.
• Documentación complementaria.
• Restricciones del ambiente operativo de ejecución.
• Ejemplos de test, salidas típicas, etc.
• Errores.
• Bibliografía utilizada.
• Documentación relativa al código.
• Documentación sobre la organización del código.
• Código fuente.

Documentación de construcción

Índice de contenido:
Es una tabla que contiene las páginas de comienzo de cada una de las partes que siguen.

Especificación:
Una descripción de lo que debe hacer el sistema, idealmente sin entrar en cómo va a hacerlo.

Arquitectura:
Debe describirse qué partición del problema se ha realizado indicando qué módulos se han usado, qué misión realiza cada uno y qué relaciones hay entre ellos.

Módulos de un nivel cualquiera:

Habrá una serie de módulos de primer nivel, cada uno de los cuales se subdividirá en otros módulos de segundo nivel y así sucesivamente hasta completar el sistema.
En cada módulo deberá describirse su utilidad global, los servicios públicos que presta y qué módulos los utilizan.
Igualmente si ciertos servicios del módulo se prestan mediante la petición de servicios a módulos de nivel inferior, deberá decirse qué módulos son utilizados por el que estamos documentando.
Normalmente un módulo subordinado estará construido en torno a la implementación de los servicios de uno o varios tipos abstractos de datos de interés para la aplicación.
Es frecuente realizar el módulo de nivel más alto como un módulo de control que solicita los servicios de más alto nivel a otros módulos subordinados, en los que delega para realizar el trabajo de otros niveles inferiores. Incluso esa estrategia es aplicable a los módulos de niveles más bajos, pero deberá evitarse acoplamientos entre módulos en los que algunos módulos de nivel bajo pidan servicios a módulos de nivel superior.
Para describir las funciones que componen un módulo se separarán las descripciones de las funciones pertenecientes al interfaz público de las demás.
Cada función se documentará indicando su finalidad. Se especificará su prototipo y se comentará la semántica, el formato y el uso de cada uno de los argumentos y del resultado, indicando asimismo las restricciones de uso si la implementación depende del sistema operativo.

Documentación de uso Manual del usuario
Se documentarán en esta sección las formas de uso del sistema a través del interfaz de usuario o de comunicaciones que se haya previsto, poniendo ejemplos de uso legal y su salida típica.
Configuración del sistema
Se comentará aquí el conjunto de valores de las constantes de configuración que el sistema asumirá por defecto, indicando sus significados y señalando las formas de hacer los cambios que puedan necesitarse.
Documentación complementaria
Restricciones del ambiente operativo de ejecución
En esta sección deben comentarse las particularidades que nuestro sistema necesite para ser ejecutado como servicios del sistema operativo o de comunicaciones que se usan de modo explícito y que podrían afectar a la portabilidad del código, etc.
Ejemplos de test, salidas típicas, etc.
Incluiremos aquí una serie de ejemplos de salidas proporcionadas por el sistema en condiciones normales de uso.
Errores
Se documentarán en esta sección los errores detectados por el sistema, sus correspondientes
mensajes de error, su significado y si son recuperables o no, indicando el procedimiento de recuperación si lo hay.
Bibliografía utilizada
Se documentará aquí la bibliografía usada para el diseño e implementación del sistema.
Documentación relativa al código
Documentación sobre la organización del código. Se indicará aquí la estructuración de los archivos que componen el código en los directorios correspondientes y toda la información necesaria para compilar y enlazar los distintos módulos que se hayan usado, tanto los implementados directamente por el desarrollador como los archivos objeto y las bibliotecas no estándares que deban utilizarse.
Código fuente
Por último se acompaña un listado organizado por módulos del sistema objeto del trabajo, junto a los archivos auxiliares necesarios para su instalación, configuración, compilación, enlace y ejecución.